| ## Charlie Calvert's C++ Builder Unleashed # - 3 - C++Builder and the VCL In this chapter you will get a look at the interface between BCB and the Object Pascal code found in the VCL. This is a subject you need to understand if you want to take full advantage of the power of Borland C++Builder. There are very few occasions when BCB programmers have to think explicitly about the fact that the VCL is written in Object Pascal. Most of the time you can forget its Delphi-based heritage without fear of missing out on anything important. There are, however, a few times when Object Pascal affects your programming. Almost all my descriptions of those occasions are concentrated in this chapter. Throughout most of the rest of this book the subject will never even arise. The material in this chapter is divided into three main sections: 1. Understanding the VCL 2. Changes to the C++ Language 3. Classes created to imitate Object Pascal simple types that do not exist in C++ ## Understanding the VCL All VCL objects are referenced as pointers. There is no such thing as a static or local instance of a VCL object. You are always working with a pointer to a VCL object. This is the result of the VCL's origin in the world of Object Pascal. Delphi sought to simplify its syntax to the greatest degree possible. However, there were several hurdles that had to be crossed before the language could be made accessible to a wide variety of programmers. In particular, something had to be done about the complexity of dealing with pointers. For various reasons related to performance and wise use of memory, it is usually best to declare an object on the heap, rather than on the stack, particularly if you are still inhabiting the segmented world of 16-bit programming. As a result, the designers of Object Pascal wanted to make it as simple as possible for their users to work with objects that live on the heap. Rather than inflict pointer syntax on unwary Object Pascal programmers, the creators of the VCL decided that all objects would necessarily be created on the heap, but would support the syntax associated with local objects. In short, they created a world that eliminated pointer syntax for objects altogether. They could afford to do this because they made it impossible to create an object that was not a pointer. All other language types, such as strings, integers, arrays, structures, and floating-point numbers, could be treated either as pointers or as static objects. This rule applied only to objects. It might help to illustrate this point with examples. Here is hypothetical code for how an Object Pascal programmer might have treated objects according to the standard rules of Pascal:
    var

      S: ^TObject;

    begin

      S := New(Tobject, Create);

      S^.DoSomething;

      S^.Free;

    end;
The preceding code will not compile in Delphi, but it is an example of how Delphi code might have looked had the developers not done something to simplify matters. In particular, Delphi eliminated some syntactical clutter by enabling you to write the following:
    var

      S: TObject;

    begin

      S := TObject.Create;

      S.DoSomething;

      S.Free;

    end;
Clearly this is an improvement over the first example. However, both samples produce essentially the same underlying machine code. In other words, both examples allocate memory for the object, call a constructor called `Create`, implicitly call a method called `DoSomething`, call a destructor called `Destroy`, and then `Free` the memory associated with the object. In the second example, all of this can be done without any need to dereference a pointer with the "`^`" symbol or without making explicit reference to the act of allocating memory. The point being that the compiler knows that the variable `S` has to be a pointer to an object, because Object Pascal forbids the creation of objects that are not pointers. Clearly, in the Object Pascal world, it made sense to decide that all objects had to be pointers. There is no significant overhead involved with using pointers, and indeed they are often the fastest way to manipulate memory. So why not make this one hard and fast rule in order to make everyone's life simpler? Translate this same concept into C++, and suddenly the rule doesn't make quite as much sense. In particular, you can only dare go so far when changing the C++ language to accommodate a new paradigm, and you therefore can't reap any of the benefits that adhered to the Object Pascal code shown in the second of the two most recently listed code samples. In other words, C++ reaps no benefits from this rule, while it does tend to limit your choices. In other words, you are no longer free to create VCL objects locally, but must perforce create them on the heap, whether you want to or not. I will therefore take it as a given that the need to create VCL objects on the heap is not particularly beneficial to C++ programmers. On the other hand, there is no particular hardship inherent in doing so, nor does it force you to endure any hit on the performance of your application. It is therefore merely a fact of life, neither inherently good nor inherently bad. If you find this unduly irksome, you might consider the many other benefits that BCB brings you, and consider this one limitation as a small price to pay for getting the benefit of this product's strengths. One final, and not at all unimportant, point: Only VCL objects have to be created on the heap. All standard C++ objects can be handled as you see fit. In other words, you can have both static or dynamic instances of all standard C++ objects. It's only VCL objects that must be addressed with pointers and must be allocated on the heap! ## Changes to the C++ Language It's now time to wrap up the introductory portion of this chapter, which provided an overview of the VCL and BCB programming. The next subject on the agenda involves how the VCL has impacted the C++ language and how the C++ language has affected the VCL. It's perhaps simplest to start with a run down of the new features in the C++ language. I am, of course, aware of how controversial it is to add extensions to C++. However, I personally am only interested in good technology and the quality of the products I use. BCB is a good product, and part of what makes it good is the power of the VCL and the power of the component, property, event model of programming. The new extensions have been added to the language to make this kind of programming possible, and so I am in favor of these changes. The C++ committee has done excellent work over the years, but no committee can keep up with the furious pace of change in this industry. The following extensions have been added to the language in order to support the VCL and the component, property, and delegation model of programming:
    _ _declspec(delphiclass | delphireturn)

    _ _automated

    _ _published

    _ _closure

    _ _property

    _ _classid(class)

    _ _fastcall
As you can see, all of these keywords have two underscores prefixed to them. In this instance, I have separated the underscores with a single space to emphasize the fact that not one, but two underscores are needed. In your programs, the underscores should be contiguous, with no space between them. I am going to go through all these new keywords and make sure that you understand what each means. The purpose of each of these sections is not to explain the how, when, where, and why of a particular keyword, but only to give you a sense of what you can and can't do with them. I will also say something about the relative importance of each new piece of syntax. My goal is to create a handy reference for the new keywords, but I will wait until later to explain most of them in real depth. For instance, a lengthy discussion of the `__automated` keyword appears in Chapter 27, "Distributed COM," which covers DCOM and Automation, and I discuss properties at length in Chapters 19 through 24, which cover creating components. ### Automated The automated keyword is for use in OLE automation classes. Only classes that descend from `TAutoObject` or a descendant of `TAutoObject` would have a use for this keyword. Here is an example of a class that sports an automated section:
    class TMyAutoObject : public TAutoObject

    {

    private:

    public:

      virtual __fastcall TMyAutoObject();

    __automated:

      AnsiString __fastcall GetName(void) { return "MyAutoObject"; }

    };
If this class were compiled into a working program, the `GetName` function would be available to other programs through OLE automation. They can call the function and it will return the word `"MyAutoObject"`. The reason the `GetName` function can be accessed through OLE automation is because it appears in the automated section of an object. Notice that it is also declared `__fastcall`. This is necessary with automated functions. It means the compiler will attempt to pass the parameters in registers rather than on the stack. The `__automated` directive makes OLE automation programming much easier, but it's effect is limited to this one area. It has no far reaching effect on the whole of the C++ language. ### The Published Keyword In addition to public, protected, and private, C++ now supports two new keywords used to delineate a section in a class declaration where properties that are to appear in the Object Inspector can be declared. If you are creating a component with new properties that you want to appear in the Object Inspector, you should place those properties in the published section. Properties that appear in the published section have very complete RTTI generated for them by the compiler. It is only legal to use the __`published` keyword in VCL classes. Furthermore, though the compiler may or may not enforce the rule, it is generally not sensible to use the `__published` keyword in objects that do not descend from `TComponent` or from a descendant of `TComponent`. The reasoning here is simply that `TComponent` is a necessary ancestor of all components, and the `__published` keyword exists because it helps to enhance components. The RTTI associated with the `__published` section will have some effect on program performance, so you don't want to use it unless it will be helpful. Therefore, use `__published` only in classes that you want to make into components. Here is an example of an object that features a published section:
    class TMyObject : public TComponent

    {

    private:

      int FSomeInteger;

    protected:

      int AnotherInteger;

    public:

      int PublicInteger;

    __published:

      __property int SomeInteger={read=FSomeInteger, write=FSomeInteger};

    };
In this declaration, the property called `SomeInteger` is published, will be illuminated with RTTI, and will appear in the Object Inspector if you install `TMyObject` as a component. The `__published` directive changes the way I think about classes, and it changes the way I write code. It currently has significance only for VCL classes and for your components. At this time it has no far-reaching implications in regard to the structure of the C++ language. It is just something that aids in the construction of VCL components. ### Properties Properties represent one of the most important, and most beneficial additions to C++ that you will find in BCB. There will be several places in this book where I discuss properties in depth. In this section I simply give you a general outline of the key points regarding this subject. Properties have four primary purposes: 1. They support a technology that allows you to expose part of an object to visual programmers via the Object Inspector. 2. They provide an excellent means of creating a rigidly defined, and thoroughly correct, interface for an object. 3. They make it easy for you to protect the private data of an object, and the private portions of your implementation. 4. They support a very sophisticated form of RTTI which allows them to be both seen in the object inspector, and to be automatically streamed out to and read from disk without intervention from the programmer. The automatic streaming of objects is one of the great features of the VCL. Properties can be added to either the `public` or `published` section of a class declaration. It makes no sense to put them in either the `protected` or `private` sections, because their primary purpose is to provide a public interface to your object. Here is a declaration for a property:
    class TMyObject : public TComponent

    {

    private:

      int FSomeInteger;

    __published:

      __property int SomeInteger={read=FSomeInteger, write=FSomeInteger};

    };
In this class, `SomeInteger` is a property of type `int`. It serves as the public interface for the private `FSomeInteger` variable. To declare a property: Use the `__property` keyword. Declare the type of the property. Add the name of the property. Add an equal sign and an open and close curly brace followed by a semicolon. Between the curly braces, properties can have read and write sections. These sections are used to designate how to set or get the value of a property. To declare the read section, write the word read followed by an equal sign, and do the same thing with the write section. It is very common in VCL classes to declare `private` data with the letter `F` prefixed to it. The letter `F` stands for field. It serves as a reminder that this is a `private` variable and should not be accessed from another class. You can declare a property to be read only or write only:
    __property int SomeInteger={read=FSomeInteger};

    __property int SomeInteger={write=FSomeInteger};
The first of these declarations is read only, the second is write only. Because `FSomeInteger` is private, you might need to provide some means of accessing it from another object. You can and should sometimes use the `friend` notation, but that really violates the whole concept of the `private` directive. If you want to give someone access to your data, but continue to hide the specific implementation of that data, use properties. The preceding code provides one means of giving someone access to your data while still protecting it. It goes without saying that if your property does nothing else but call directly to a variable of the same type in the `private` section, the compiler generates code that gives you direct access to the type. In other words, it doesn't take any longer to directly use a property like `SomeInteger` than it would to use `FSomeInteger` directly. The compiler takes care of the details for you, and uses less code than it would with an inline access function. NOTE: C++ programmers have long used get and set methods to provide access to `private` data. There is a certain amount of controversy as to whether or not properties add something to the object model outside of their capability to be seen in the Object Inspector. Here is a second way to state the matter. Given the presence of the Object Inspector, properties clearly play an important role in BCB programming. A second debate, however, would involve the question of whether or not--absent the issue of the Object Inspector--properties add something new to the mix that would not be there if we had only access functions and get and set methods. One thing I like a great deal about properties is the clarity of the syntax they present to the user. They make it easier to write clear, maintainable code. They also do a very good job of helping you protect the low-level implementation of your object. I recognize, however, that it could be argued that access functions provided sufficient power to accomplish these goals without the aid of properties. I could safely hide behind the fact that the BCB programming model demands the presence of properties. However, I will stick my neck out on this one and say that I feel properties are an important contribution to C++, and should become part of the language. I recognize, however, that this is the kind of subject that fosters intense controversy, and concede that the debate is not entirely one-sided. Here is another use of properties that differs from the one just shown:
    class MyObject : public TObject

    {

    private:

      int FSomeInteger;

      int __fastcall GetSomeInteger() { return FSomeInteger; }

      void __fastcall SetSomeInteger(int i) { FSomeInteger = i; }

    __published:

      __property int SomeInteger={read=GetSomeInteger, write=SetSomeInteger};
    };
In this class, `SomeInteger` has get and set methods. These get and set methods are associated with a property and should always be declared with the `__fastcall` calling convention. Get and set methods provide a means of performing calculations or other actions when getting and setting the value of a property. For instance, when you change the `Width` property in a `TShape` object, not only does some internal variable get set, but the whole object redraws itself. This is possible because there is a set method for this property that both sets the internal `FWidth` property to a new value and redraws the object to reflect these changes. You could perform calculations from inside a get method. For instance, you could calculate the current time in a property designed to return the current time. The existence of get and set methods represents another important reason for keeping the data of your object `private`, and for not giving anyone else access to it except through properties. In particular, you may change a value in a set or get method or have side effects that you want to be sure are executed. If someone accesses the data directly, the side effects or other changes will not occur. Therefore, you should keep the data `private` and let them access it through a function, and let the function itself be accessed through a property. Properties can be of a wide variety of types. For instance, they can be declared as `AnsiString`s, arrays, sets, objects, or enumerated types. Events, which are a kind of method pointer, are really a type of property, but they behave according to their own peculiar rules and are usually treated as a separate subject from properties. Properties can be declared to have a default value:
    __property int SomeInteger={read=GetSomeInteger, write=SetSomeInteger, default=1};
This syntax is related only tangentially to the concept of setting a property automatically to a particular value. If you want to give a property a predefined value, you should do so in the object's constructor. Default is used to tell the VCL whether or not a value should be written out to a stream. The issue here is that streaming can result in producing large files, because so many objects have such large numbers of properties. To cut down on the size of your form files, and on the time spent writing the files to disk, the VCL enables you to declare a default value for a property. When it comes time to stream properties to disk, they will not be streamed if they are currently set to the default value. The assumption is that you will initialize them to that value in the object's constructor, so there is no need to save the value to disk. Many properties are declared to be nodefault, which means they should be streamed to disk. A property can also have the stored directive. Confusingly enough, this is another means of deciding whether or not a property should be streamed. In this case, it gives you the option of changing whether or not a property can be streamed. For instance:
    property TColor Color={read Fcolor, write SetColor,

      stored=IsColorStored, default=clWindow};
This property calls a method named `IsColorStored` to determine whether the color should be stored at this time. For instance, if the property is set to have the same value as its parent, there is no need to store it, and `IsColorStored` returns `False`. This property will therefore only be stored if `IsColorStored` returns `True` and the color is not set to `clWindow`. Say what? Don't worry, most of the time you don't have to get involved with these tricky storage specifiers and their disarming schemes to save disk space. However, there are times when the matter comes to the front, and now you have a place to look to remember what they mean. Properties play a big role in VCL programming, and furthermore, they can be used in objects that have nothing to do with the VCL. This subject has tremendous potential scope and will affect the way the C++ language as a whole is handled by BCB programmers. That is all I'm going to say about properties for now. There is an example of creating and using an array property later in this chapter in the section called "Arrays of AnsiStrings." ### Events: Understanding Delegation Most of the time I will refer to closures as events. Technically, a closure is the type of method pointer used in event properties, but I will generally refer to the whole syntactical structure as an event that supports the delegation model. As you learned in the last section, an event is really a kind of property. The primary difference between a standard property and an event is that the type of an event is a method pointer. NOTE: Some people refer to events as closures, but it could be argued that the word has a rather stuffy, academic overtone to it. Certainly it is used in some circles in a very strict manner that does not necessarily conform in all its particulars to the way BCB handles events. Consider the `OnMouseUp` event that is supported by many components and declared in `CONTROLS.HPP`:
    __property TMouseEvent OnMouseUp = {read=FOnMouseUp, write=FOnMouseUp};
Like the `OnMouseUp` property, `FOnMouseUp` is, naturally, also declared to be of type `TMouseEvent`:
    TMouseEvent FOnMouseUp.
So far the syntax used for events seems pretty much identical to that used for all properties. The new code that is specific to the delegation model is the actual declaration for the method pointer used by an event:
    typedef void __fastcall (__closure *TMouseEvent)(System::TObject* Sender,

      TMouseButton Button, Classes::TShiftState Shift, int X, int Y);
All `OnMouseUp` events are of this type. In other words, if an `OnMouseUp` event is not set to `null`, it is set to a method pointer of this type. You can then call the event by writing code of this type:
    if (FOnMouseUp)

      FOnMouseUp(this, Button, Shift, X, Y);
If the event is not set to `null`, call the method associated with the event and pass parameters of a type that conform with the signature of the relevant method pointer. This is called delegating the event. NOTE: It is generally considered very bad form to return a value from an event. Trying to do so could cause a compiler error, and you should avoid including code of this type in your own programs. The VCL has gone through several iterations now, and returning values from events has worked in some versions and not in others. The team that wrote the VCL, however, asked the DOC team to state explicitly that events should not return values. It usually turns out badly when you get stuck with legacy code that worked in one version, but directly contradicts the desires of the folks who keep the reins in their own hands. The method associated with the `OnMouseUp` event will look something like this:
    void __fastcall TForm1::Button1MouseUp(

      TObject *Sender,

      TMouseButton Button,

      TShiftState Shift,

      int X,

      int Y)

    {

    }
I generally call a method of this type an event handler. It handles an event when it is delegated by a component or object. Most of the time an event is assigned to a method automatically by the compiler. However, you can do so explicitly if you desire, and in fact I do this in several places in my own code. If you want an example, see the Music program from Chapter 16, "Advanced InterBase Concepts." Here is how the assignment would be made from inside the Controls unit:
    FOnMouseEvent = Button1MouseUp;
Code of this type appears everywhere in the VCL, and indeed it is one of the central constructs that drives BCB. This is the heart of delegation programming model. As I have said several times, BCB is primarily about components, properties, and the delegation model. Take events away, and you have some other product altogether. Events radically change the way C++ programs are written. The key effect of events on C++ seems to me to be the following: "In addition to using inheritance and virtual methods to change the behavior of an object, BCB allows you to customize object by delegating events. In particular, VCL objects often delegate events to the form on which they reside." Like all properties, events work with both standard C++ classes and with VCL classes. ### declspec(delphiclass | delphireturn | pascalimplementation) All the additions to C++ discussed so far are primarily about finding ways to support the VCL. In particular, the new VCL object model has certain benefits associated with it, and so Borland has extended C++ in order to accommodate this new model. The property and event syntax, however, appears to have at least some other implications beyond its simple utilitarian capability to support the VCL. I think you will find the next three changes are very small potatoes compared to properties and events. All they really do is make it possible for BCB to use the VCL, and they don't really have much effect at all on the way we write code. As you have no doubt gleaned by this time, VCL classes behave in specific ways. For instance, a VCL class can only by instantiated on the heap, and you can only use the `__published` or `__automated` keywords with VCL classes. The majority of the time your own classes can inherit this behavior directly, simply by descending from a VCL class. For instance, here is part of the declaration for `TControl`
    class __declspec(pascalimplementation) TControl : public Classes::TComponent

    {

      typedef Classes::TComponent inherited;

    private:

      TWinControl* FParent;

      ... // etc

    }
As you can see, these classes are declared with the `delphiclass` or `pascalimplementation` attribute. This means they are implemented in Pascal, and the headers are the only part that appear in C++ code. If you have an Object Pascal unit that you want to use in a BCB application, the other declarations in the unit will automatically be translated and placed in a C++ header file. The class declarations in that header file will be similar to the one shown here. However, if you create a descendant of `TControl`, you don't have to bother with any of this, because the attributes will be inherited:
    class MyControl : public TControl

    {

      // My stuff here

    }
Class `MyControl` is automatically a VCL class that can support __`published` properties and must be created on the heap. It inherits this capability from `TControl`. As a result, it is implicitly declared `pascalimpementation`, even though you don't explicitly use the syntax. I don't like to clutter up class declarations with `__declspec(pascalimplementation)`, but it may appeal to some programmers because it makes it clear that the class is a VCL class and has to be treated in a particular manner. If you want to create a forward declaration for a class with the `pascalimplementation` attribute, it must have the `delphiclass` attribute:
    class __declspec(delphiclass) TControl;
This is a forward declaration for the `TControl` class found in `CONTROLS.HPP`. You do not inherit `delphiclass` in the same sense that you do `pascalimplementation`, and so you must use it explicitly in forward declarations! `delphireturn` is used to tell the compiler to generate a particular kind of code compatible with the VCL when it returns objects or structures from a function. The only place in BCB where this is done is in `SYSDEFS.H` and `DSTRINGS.H`, which is where classes like `Currency`, `AnsiString`, and `Variant` are declared. If you need to return objects or structures to the VCL, you may need to declare your class with this directive. However, there are very few occasions when this is necessary, and most programmers can forget about `delphireturn` altogether. NOTE: As shown later in this chapter, the `TDateTime` object is declared `delphireturn`. This is necessary because instances of the object can be passed to VCL functions such as `DateTimeToString`. All of this business about `dephireturn` and `pascalimplementation` has little or no effect on the code written by most BCB programmers. `delphiclass` is slightly more important, because you will likely have occasion to declare a forward declaration for one of your own descendants of a VCL class. This is clearly a case where you can indeed afford to "pay no attention to the man behind the curtain." Most of this stuff is just hand signals passed back and forth between the compiler and VCL, and you can afford to ignore it. Its impact on the C++ programming as a whole is essentially nil. ### classid(class) Use `classid` if you need to pass the specific type of a class to a function or method used by the VCL RTTI routines. For instance, if you want to call the `ClassInfo` method of `TObject`, you need to pass in the type of the class you want to learn about. In Object Pascal you write
    ClassInfo(TForm);
which means: Tell me about the `TForm` class. Unfortunately, the compiler won't accept this syntax. The correct way to pose the question in BCB is
    ClassInfo(__classid(TForm));
Again, this is just the compiler and the VCL having a quiet little chat. Pay no attention to the man behind the curtain. RTTI looks one way in the VCL, another in standard C++. This syntax is used to bridge the gap between the two, and it has no far reaching implications for C++, the VCL, or anyone else. The excitement is all centered around the property and event syntax; this is a mere trifle. ## __fastcall The default calling convention in Object Pascal is called `fastcall`, and it is duplicated in C++Builder with the `__fastcall` keyword. `__fastcall` methods or functions usually have their parameters passed in registers, rather than on the stack. For instance, the value of one parameter might be inserted in a register such as `EAX` and then snagged from that register on the other side. The `__fastcall` calling conventions pass the first three parameters in `eax`, `edx`, and `ecx` registers, respectively. Additional parameters and parameter data larger than 32 bits (such as doubles passed by value) are pushed on the stack. ## Delphi-Specific Classes Not all the features of C++ are available in Object Pascal, and not all the features of Object Pascal are available in BCB. As a result, the following classes are created to represent features of the Object Pascal language that are not present in C++:
    AnsiString

    Variant

    ShortString

    Currency

    TDateTime

    Set
Most of these classes are implemented or declared in `SYSDEFS.H`, though the crucial `AnsiString` class is declared in its own file called `DSTRINGS.H`. NOTE: Neither the `real` nor `comp` types used in Object Pascal are supported adequately in BCB. Because Pascal programmers often used the `comp` type to handle currency, they should pay special attention to the section in this chapter on the BCB currency type. The real type is an artifact of the old segmented architecture days when anything and everything was being done to save space and clock cycles. It no longer plays a role in contemporary Object Pascal programming. I will dedicate at least one section of this chapter to each of the types listed previously. Some important types, such as `Sets` and `AnsiStrings`, will receive rather lengthy treatment stretching over several sections. Many C++ programmers will have questions about the presence of some of these classes. For instance, C++ comes equipped with a great set template and an excellent string class. Why does BCB introduce replacements for these classes? The answer to the question is simply that BCB needed a class that mimicked the specific behavior of Object Pascal sets and Object Pascal strings. Here are some macros you can use with these classes:
    OPENARRAY

    ARRAYOFCONST

    EXISTINGARRAY

    SLICE
These macros are also discussed in the upcoming sections. ## Introducing the AnsiString Class The C language is famous for its null-terminated strings. These strings can be declared in many ways, but they usually look like one of these three examples:
    char MyString[100]; // declare a string with 100 characters in it.

    char *MyString;     // A pointer to a string with no memory allocated for it.

    LPSTR MyString;     // A "portable" Windows declaration for a pointer to a string
Declarations like these are such a deep-rooted and long standing part of the C language that it is somewhat shocking to note that they are not as common as they once were. There is, of course, nothing wrong with these strings, but C++ has come up with a new, and perhaps better, way to deal with strings. (I speak of these strings as being exclusive to C, though of course these same type of strings are also used in Object Pascal, where they are called `PChars`.) The "old-fashioned" types of strings shown previously cause people problems because it is easy to make memory allocation errors with them or to accidentally omit the crucial terminating zero (``/0'`) that marks the end of these strings. These same strings are also famous for their accompanying string library, which includes a series of cryptic looking functions with names like `strcpy`, `strlen`, `strcmp`, `strpbrk`, `strrchr`, and so on. These functions, most of which occur in both C++ and Object Pascal, can be awkward to use at times, and can frequently lead to errors if a programmer gets careless. In this book, I will try to avoid using any of the "old fashioned" C style strings whenever possible. Instead, I will do things the C++ way and use string classes. Most C++ programmers prefer string classes on the grounds that they are easier to use, easier to read, and much less likely to lead to an error involving memory allocation. In this book there is a fourth reason for using string classes. In particular, a string class called `AnsiString` provides compatibility with the underlying strings found in the VCL. C++ programmers will find that `AnsiString`s are similar to the standard ANSI C++ `String` class. `AnsiString`s are very easy to use. In fact, many programmers will find that they have an intuitive logic to them that almost eliminates the need for any kind of in-depth explanation. However, `AnsiString`s happen to form one of the key building blocks on which a great deal of C++Builder code is based. It is therefore of paramount importance that users of BCB understand `AnsiString`s. The next few sections of the book take on the task of explaining `AnsiString`s. To help illustrate this explanation with ready-made examples, you can turn to the UsingAnsiString program found on the book's CD-ROM. This program provides examples of essential `AnsiString` syntax and shows several tricks you can use when you add strings to your programs. ### Working with the AnsiString Class The `AnsiString` class is declared in the `DSTRING.H` unit from the `..\INCLUDE\VCL` directory. This is a key piece of code, and one which all BCB programmers should take at least a few minutes to study. The declaration for the class in the `DSTRING.H` unit is broken up into several discreet sections. This technique makes the code easy to read. For instance, one of the sections shows the operators used for assignments:
    // Assignments

        AnsiString& __fastcall operator =(const AnsiString& rhs);

        AnsiString& __fastcall operator +=(const AnsiString& rhs);
Another section shows some comparison operators:
    //Comparisons

        bool __fastcall operator ==(const AnsiString& rhs) const;

        bool __fastcall operator !=(const AnsiString& rhs) const;

        bool __fastcall operator <(const AnsiString& rhs) const;

        bool __fastcall operator >(const AnsiString& rhs) const;

        bool __fastcall operator <=(const AnsiString& rhs) const;

        bool __fastcall operator >=(const AnsiString& rhs) const;
Another handles the `Unicode`-related chores:
    //Convert to Unicode

        int __fastcall WideCharBufSize() const;

        wchar_t* __fastcall WideChar(wchar_t* dest, int destSize) const;
There is, of course, much more to the declaration than what I show here. However, these code fragments should give you some sense of what you will find in `DSTRING.H`, and of how to start browsing through the code to find `AnsiString` methods or operators that you want to use. The rest of the text in this section of the chapter examines most of the key parts of the `AnsiString` class and shows how to use them. However, you should definitely find time, either now or later, to open up `DSTRING.H` and to browse through its contents. ### AnsiString Class Constructors `AnsiString`s are a class; they are not a simple type like the string type in Object Pascal, which they mimic. Object Pascal or BASIC programmers might find that the next line of code looks a little like a simple type declaration. It is not. Instead, this code calls the constructor for an object:
    AnsiString S;
Here are the available constructors for the `AnsiString` class:
    __fastcall AnsiString(): Data(0) {}

    __fastcall AnsiString(const char* src);

    __fastcall AnsiString(const AnsiString& src);

    __fastcall AnsiString(const char* src, unsigned char len);

    __fastcall AnsiString(const wchar_t* src);

    __fastcall AnsiString(char src);

    __fastcall AnsiString(int src);

    __fastcall AnsiString(double src);
The simple `AnsiString` declaration shown at the beginning of this section would call the first constructor shown previously, which initializes to zero a private variable of the `AnsiString` class. This private variable, named `Data`, is of type `char *`. `Data` is the core C string around which the `AnsiString` class is built. In other words, the `AnsiString` class is a wrapper around a simple C string, and the class exists to make it easy to manipulate this string and to make the string compatible with the needs of the VCL. The following simple declaration would call the second constructor shown in the previous list:
    AnsiString S("Sam");
> This is the typical method you would use when initializing a variable of type `AnsiString`. NOTE: I have included a second example program called `UsingAnsiString2`, which features a small class that overrides all the constructors for the `AnsiString` class:
>     class MyAnsiString : public AnsiString

>     {

>     public:

>       __fastcall MyAnsiString(void): AnsiString() {}

>       __fastcall MyAnsiString(const char* src): AnsiString(src) {}

>       __fastcall MyAnsiString(const AnsiString& src): AnsiString(src) {}

>       __fastcall MyAnsiString(const char* src, unsigned char len): AnsiString     (src, len) {}

>       __fastcall MyAnsiString(const wchar_t* src): AnsiString(src) {}

>       __fastcall MyAnsiString(char src): AnsiString(src) {}

>       __fastcall MyAnsiString(int src): AnsiString(src) {}

>       __fastcall MyAnsiString(double src): AnsiString(src) {}

>     };
This class is provided so you can step through the constructors to see which ones are being called. For instance, the three constructors shown immediately after this note have been rewritten in the UsingAnsiStrings2 program to use `MyAnsiStrings` rather than `AnsiString`s. This gives you an easy-to-use system for explicitly testing which constructors are being called in which circumstance. When I come up with a unit like this that may be of some general utility in multiple programs, I usually put it in the `utils` subdirectory located on the same level as the chapter subdirectories. In other words, I move or copy it out of the directory where the files for the current program are stored and place it in a subdirectory called `utils` that is on the same level as the directories called `Chap01`, `Chap02`, and so on. You might need to add this directory to the include search path for your project, or the program might not be able to find the `MyAnsiString.h` unit. To set up the compiler for your system, go to Options | Project | Directories/Conditionals and change the Include Path to point to the directory where `MyAnsiString.h` is stored. Sometimes I will leave one frozen copy of a unit in the directory where it was first introduced and continue development of the copy of the unit that I place in the `utils` subdirectory. That way, you can find one copy of the file that looks the way you expect it to look in the same directory as the program in which I introduce it, while continuing to develop the code in a separate unit of the same name found in the `utils` directory. Check the `Readme.txt` file on the CD that accompanies this book for further information. The following are a few simple examples from the UsingAnsiStrings program that show examples of creating and using `AnsiString`s:
    void __fastcall TForm1::PassinCString1Click(TObject *Sender)

    {

      AnsiString S("Sam");

      Memo1->Text = S;

    }

    void __fastcall TForm1::PassInInteger1Click(TObject *Sender)

    {

      AnsiString MyNum(5);

      Memo1->Text = MyNum;

    }

    void __fastcall TForm1::PassInaDouble1Click(TObject *Sender)

    {

      AnsiString MyDouble(6.6);

      Memo1->Text = MyDouble;

    }
This code demonstrates several things. The first, and most important point, is that it shows how you can create an `AnsiString` object by initializing it with a string, an integer, or a double. In short, these constructors can automatically perform conversions for you. This means you can usually write code like this:
    AnsiString S;

    int I = 4;

    S = I;

    ShowMessage(S);
When working with C strings, you always have to be careful that the variable you have been working with has been properly initialized. This is not nearly as big a concern when you are working with `AnsiString`s. Consider the following code:
    void __fastcall TForm1::InitializetoZero1Click(TObject *Sender)

    {

      AnsiString S;

      Memo1->Text = S.Length();

    }
The first line creates an `AnsiString` class that has a zero length string. The second line performs a completely safe and legal call to one of the methods of this `AnsiString`. This is the type of situation that can be very dangerous in C. Here, for instance, is some code that is likely to blow up on you:
    char *S;

    int i = strlen(S);
This code appears to do more or less the same thing as the code in the `InitializetoZero1Click` method. In practice, however, this latter example actually raises an access violation, while the `AnsiString` code example succeeds. The explanation is simply that the declaration of the `AnsiString` class created a real instance of an object called `S`. You can safely call the methods of that object, even if the underlying string has no memory allocated for it! The second example, however, leaves the `char *` declared in the first line completely impotent, with no memory allocated for it. If you want to avoid trouble, you should not do anything with that variable until you allocate some memory for it. In the last few paragraphs I have outlined an example illustrating what it is I like about the `AnsiString` class. In short, this class makes strings safe and easy to use. NOTE: It goes without saying that C strings are generally faster than `AnsiString`s, and that they take up less memory. Clearly, these are important features, and obviously I am not stating that C strings are now obsolete. The reasoning on this issue is a bit like that we undertake when deciding whether to buy a car or a motorcycle. Cars are more expensive than motorcycles, and they don't let you weave back and forth between lanes when there is congested traffic. On the other hand, drivers of cars are much less likely to end up in the hospital, and cars are much more pleasant to be in during inclement weather. In the same way, `AnsiString`s aren't as small and flexible as C strings, but they are less likely to crash the system, and they stand up better when you are in a rush or when handled by inexperienced programmers. This book focuses on ways to quickly write safe, high-performance programs. If that is your goal, use `AnsiString`s. If you are trying to write an operating system, a compiler, or the core module for a 3D game engine, you should probably concentrate more on speed than I do in this book and should use `AnsiString`s only sparingly. Please note that my point here is not that you can't use C++Builder to write highly optimized code, but only that this book usually does not focus on that kind of project. ### Sticky Constructor Issues The `AnsiString` constructors are easy to use, but things can be a bit confusing if you try to think about what is going on behind the scenes. For instance, consider what happens when you pass an `AnsiString` to a function:
    AnsiString S;

    MyFunc(S);
If the call to `MyFunc` is by value, not by reference, the constructor for `S` is going to be called each time you pass the string. This is not a tremendous burden on your program, but it is probably a bit more significant weight than you had in mind to impose on your code. As a result, you should pass in the address of the variable in most circumstances:
    AnsiString S;

    MyFunc(&S);
Even better, you should construct methods that declare all their string variables as being passed by reference:
    int MyFunc(AnsiString &S)

    {

      S = "The best minds of my generation...";

      return S.Length();

    }
This is like a `var` parameter in Object Pascal in that it lets you pass the string by reference without worrying about pointers:
    void __fastcall TForm1::Button1Click(TObject *Sender)

    {

      AnsiString S;

      int i = MyFunc(S);

      ShowMessage(S + " Length: " + i);

    }
Even when `MyFunc` changes the string, the result of the changes is reflected in the calling module. This syntax passes a pointer to the function, but makes it seem as though you are working with a local stack-based variable on both the caller and calling sides. Consider the following code samples:
    MyAnsiString S = "The road to the contagious hospital";

    MyAnsiString S1 = AnsiString("If I had a green automobile...");

    MyAnsiString S2("All that came out of them came quiet, like the four seasons");

    ShowMessage(S + `\r' + S1 + `\r' + S2);
It should be clear from looking at this code that the second example will take longer to execute than the third, because it calls two constructors rather than just one. You might also think that the first takes longer than the third. A logical course of reasoning would be to suppose that, at minimum, it would have to call both a constructor and the equals operator. In fact, when I stepped through the code, it became clear that the compiler simply called the constructor immediately in the first example, and that the machine code executed for the first and third examples was identical. What is the lesson to be learned here? Unless you are writing a compiler, an operating system, or a 3D game engine, just don't worry about this stuff. Of course, if you love worrying about these issues, then worry away. I suppose someone has to. Otherwise, relax. There is almost no way to tell from looking at the code what the compiler is going to do, and 90 percent of the time the compiler is smart enough to generate optimal code unless you explicitly tell it to go out of its way, as I do in the second example. If you are a beginning- or intermediate-level programmer, someone is going to tell you that you should pull your hair out worrying about optimization issues like this. Personally, I think there are more important subjects to which you can dedicate your time. Eliminating one constructor call might save a few nanoseconds in execution time, but nobody is going to notice it. Learn to separate the petty issues from the serious issues. Most importantly of all, wait until you have a program up and running before you decide whether or not you have a performance bottleneck. If the program is too slow, use a profiler to find out where the bottlenecks are. Ninety-eight percent of the time the bottlenecks are in a few isolated places in the code, and fixing those spots clears up the problem. Don't spend two weeks looking for every place there is an extra constructor call only to find it improves your performance by less than one percent. Wait till you have a problem, find the problem, and then fix it. If it turns out that you are in a loop, and are making extra constructor calls in the loop, and that by doing some hand waving to get rid of the calls you improve program performance by 10 percent, then great. But don't spend days working on "optimizations" that end up improving performance by only one or two percent. ### AnsiString Comparison Operators Comparison operators are useful if you want to alphabetize strings. For instance, asking if `StringOne` is smaller than `StringTwo` is a means of finding out whether `StringOne` comes before `StringTwo` in the alphabet. For instance, if `StringOne` equals `"Dole"` and `StringTwo` equals `"Clinton"`, `StringOne` is larger than `StringTwo` because it comes later in the alphabet. (At last, a politically controversial string comparison analysis!) Here are the `AnsiString` class comparison operators and methods:
    bool __fastcall operator ==(const AnsiString& rhs) const;

    bool __fastcall operator !=(const AnsiString& rhs) const;

    bool __fastcall operator <(const AnsiString& rhs) const;

    bool __fastcall operator >(const AnsiString& rhs) const;

    bool __fastcall operator <=(const AnsiString& rhs) const;

    bool __fastcall operator >=(const AnsiString& rhs) const;

    int __fastcall AnsiCompare(const AnsiString& rhs) const;

    int __fastcall AnsiCompareIC(const AnsiString& rhs) const; //ignorecase
The UsingAnsiString program on this book's CD-ROM shows how to use these operators. For instance, the following method from that program shows how to use the equals operator:
    void __fastcall TForm1::Equals1Click(TObject *Sender)

    {

      AnsiString StringOne, StringTwo;

      InputDialog->GetStringsFromUser(&StringOne, &StringTwo);

      if (StringOne == StringTwo)

        Memo1->Text = "\"" + StringOne + "\" is equal to \"" + StringTwo + "\"";

      else

        Memo1->Text = "\"" + StringOne + "\" is not equal to \"" + StringTwo + "\"";

    }
Here is an example of using the "smaller than" operator:
    void __fastcall TForm1::SmallerThan1Click(TObject *Sender)

    {

      AnsiString String1, String2;

      InputDialog->GetStringsFromUser(&String1, &String2);

      if (String1 < String2)

        Memo1->Text = "\"" + String1 + "\" is smaller than \"" + String2 + "\"";

      else

        Memo1->Text = "\"" + String1 + "\" is not smaller than \"" + String2 + "\"";

    }
The `AnsiCompareIC` function is useful if you want to ignore the case of words when comparing them. This method returns zero if the strings are equal, a positive number if the string calling the function is larger than the string to which it is being compared, and negative number if it is not larger than the string to which it is being compared:
    void __fastcall TForm1::IgnoreCaseCompare1Click(TObject *Sender)

    {

      AnsiString String1, String2;

      InputDialog->GetStringsFromUser(&String1, &String2);

      if (String1.AnsiCompareIC(String2) == 0)

        Memo1->Text = "\"" + String1 + "\" equals \"" + String2 + "\"";

      else if (String1.AnsiCompareIC(String2) > 0)

        Memo1->Text = "\"" + String1 + "\" is larger than \"" + String2 + "\"";

      else if (String1.AnsiCompareIC(String2) < 0)

        Memo1->Text = "\"" + String1 + "\" is smaller than \"" + String2 + "\"";
    }
Consider the following chart:
`StringOne` | `StringTwo` | Result
England | England | Returns zero
England | France | Return a negative number
France | England | Returns a positive number
### Using the Pos Method The `Pos` method is used to find the offset of a substring within a larger string. Here is a simple example from the UsingAnsiString program of how to use the `Pos` function:
    void __fastcall TForm1::SimpleString1Click(TObject *Sender)

    {

      AnsiString S = "Sammy";

      Memo1->Text = S;

      int i = S.Pos("mm");

      S.Delete(i + 1, 2);

      Memo1->Lines->Add(S);
    }
This code creates an `AnsiString` initialized to the name `"Sammy"`. It then searches through the string for the place where the substring `"mm"` occurs, and returns that index so that it can be stored in the variable i. I then use the index as a guide when deleting the last two characters from the string, thereby transforming the word `"Sammy"` to the string `"Sam"`. Here is a similar case, except that this time code searches for a tab rather than an ordinary substring:
    void __fastcall TForm1::Pos1Click(TObject *Sender)

    {

      AnsiString S("Sammy \t Mike");

      Memo1->Text = S;

      AnsiString Temp = Format("The tab is in the %dth position",

        OPENARRAY(TVarRec, (S.Pos(`\t'))));

      Memo1->Lines->Add(Temp);

    }
The code in this example first initializes the `AnsiString` `S` to a string that contains a tab, and then searches through the string and reports the offset of the tab: "The tab is in the 7th position." The `Format` function shown here works in the same fashion as `sprintf`. In fact, the following code would have the same result as the `Pos1Click` method shown previously:
    AnsiString S("Sammy \x009 Mike");

    Memo1->Text = S;

    char Temp[75];

    sprintf(Temp, "The tab is in the %dth position", S.Pos(`\t'));

    Memo1->Lines->Add(Temp);
### Escape Sequences in C++ C++ uses a series of escape sequences to represent special characters such as tabs, backspaces, and so on. If you are not familiar with C++, you might find the following table of escape sequences useful:
Human readable name | Escape sequence | Hex representation
Bell | `\a` | `\x007`
Backspace | `\b` | `\x008`
Tab | `\t` | `\x009`
Newline | `\n` | `\x00A`
Form Feed | `\f` | `\x00C`
Carriage return | `\r` | `\x00D`
Double quote | `\"` | `\x022`
Single quote | `\'` | `\x027`
Backslash | `\\` | `\x05C`
Escape sequences are usually placed in single quotes, though in the previous case it would not matter whether I used single or double quotes in the `Pos` statement. Using hex values has the exact same effect as using escape sequences. For instance, the following code creates identical output to the `Pos1Click` method shown previously:
    AnsiString S("Sammy \x009 Mike");

    Memo1->Text = S;

    AnsiString Temp = Format("The tab is in the %dth position",

    OPENARRAY(TVarRec, (S.Pos(`\x009'))));

    Memo1->Lines->Add(Temp);
Though some programmers may find it simpler and more intuitive to use the Hex values shown in the last column of the table, the arcane-looking escape sequences cling on in C++ code because they are portable to platforms other than Windows and DOS. ### Arrays of AnsiStrings In this section you will see how to declare an array of `AnsiString`s. The text includes examples of how to access them as standard null-terminated strings, and how to use them in moderately complex circumstances. The following ChuangTzu program uses some Chinese quotes with a millennium or two of QA under their belt to illustrate the favorite theme of this book:
    Easy is right. Begin right

    And you are easy.

    Continue easy and you are right.

    The right way to go easy

    Is to forget the right way

    And forget that the going is easy.
This program declares this string as an `AnsiString`, and then passes it to a procedure that can break it down into a series of words. These words are passed back one at a time and added into an array. The array is then displayed in a series of one word lines in a memo control. The program appears in Listings 3.1 and 3.2. #### Listing 3.1. The header for the ChuangTzu program.
    //--------------------------------------------------------------------------

    #ifndef MainH

    #define MainH

    //--------------------------------------------------------------------------

    #include <Classes.hpp>

    #include <Controls.hpp>

    #include <StdCtrls.hpp>

    #include <Forms.hpp>

    //--------------------------------------------------------------------------

    class TChuangTzu

    {

    private:

      int FCount;

      AnsiString FWords[40];

      AnsiString GetWords(int Index);

      void SetWords(int Index, AnsiString S);

    public:

      TChuangTzu(){ FCount = 0; }

      __property AnsiString Words[int Index] = {read=GetWords, write=SetWords};

      __property int Count={read=FCount, write=FCount};

    };

    class TForm1 : public TForm

    {

    published:

      TButton *Button1;

      TMemo *Memo1;

      void __fastcall Button1Click(

      TObject *Sender);

    private:

    public:

      virtual __fastcall TForm1(TComponent* Owner);

    };

    //--------------------------------------------------------------------------

    extern TForm1 *Form1;

    //--------------------------------------------------------------------------
`#endif` #### Listing 3.2. The main module of the ChuangTzu program.
    #include <vcl.h>

    #pragma hdrstop

    #include "Main.h"

    #include "codebox.h"

    #pragma resource "*.dfm"

    TForm1 *Form1;

    ///////////////////////////////////////

    // ChuangTzu //////////////////////////

    ///////////////////////////////////////

    AnsiString TChuangTzu::GetWords(int i)

    {

      return FWords[i];

    }

    void TChuangTzu::SetWords(int i,const AnsiString s)

    {

       FCount++;

       FWords[i]=s;

    }

    AnsiString StripWords(AnsiString &S, char Token)

    {

      AnsiString TokenStr(Token);

      AnsiString Temp1;

      AnsiString Temp2 = S + ` `;

      Temp1 = strtok(S.c_str(), TokenStr.c_str());

      Temp2 = strrev(Temp2.c_str());

      Temp2.SetLength(Temp2.Length() - (Temp1.Length() + 1));

      S = strrev(Temp2.c_str());

      return Temp1;

    }

    ///////////////////////////////////////

    // Form1 //////////////////////////////

    ///////////////////////////////////////

    __fastcall TForm1::TForm1(TComponent* Owner)

      : TForm(Owner)

    {

    }

    void __fastcall TForm1::Button1Click(

      TObject *Sender)

    {

      TChuangTzu C;

      AnsiString S1;

      int i = 0;

      AnsiString S =

        "Easy is right. Begin right ";

        "And you are easy. "

        "Continue easy and you are right. "

        "The right way to go easy "

        "Is to forget the right way "

        "And forget that the going is easy.";

      do

      {

        S1 = StripWords(S, ` `);

        C.Words[i] = S1;

        i++;

      } while (S1 != "");

      for (i = 0; i < C.Count; i++)

      {

        Memo1->Lines->Add(C.Words[i]);

      }
    }
The core of this program is the `ChuangTzu` class definition:
    class TChuangTzu

    {

    private:

      int FCount;

      AnsiString FWords[40];

      AnsiString GetWords(int Index);

      void SetWords(int Index, AnsiString S);

    public:

      TChuangTzu(){ FCount = 0; }

      __property AnsiString Words[int Index] = {read=GetWords, write=SetWords};

      __property int Count={read=FCount, write=FCount};
`};` At the heart of the object is the declaration for an array of 40 `AnsiString`s:
    AnsiString FWords[40];
You can access the second member of this array with code that looks like this:
    FWords[1] = "Let some sad trumpeter stand on the empty streets at dawn."

    AnsiString S = FWords[1];
The `ChuangTzu` object provides an array property that gives you access to this private data. There is, of course, no reason why you can't declare an array of `AnsiString`s on their own without a supporting object. However, I thought it might be helpful to see how you can use an array in your program without breaking the rule about keeping the raw data of your objects `private`. Here is the declaration for the `array` property:
    __property AnsiString Words[int Index] = {read=GetWords, write=SetWords};
As you can see, it returns an `AnsiString` and can be indexed with an integer value. (There is nothing to keep you from declaring `array` properties that are indexed with `AnsiString`s!) Here is the get method for the array:
    AnsiString TChuangTzu::GetWords(int i)

    {

      return FWords[i];

    }
Notice that it takes a single integer as a parameter and returns an `AnsiString`. Here is the set method for the array:
    void TChuangTzu::SetWords(int i,const AnsiString s)

    {

      FCount++;

      FWords[i]=s;

    }
This function takes both an integer and a string as parameters. In order to call this method, you write
    ChuangTzu.Words[i] = "peace proclaims olives of endless age."
Here you can see the integer that is passed to `SetWords`, as well as a quote from Shakespeare's 107 sonnet that is passed in the second parameter. The `FCount` variable is used to track the number of entries in the array. Note that properties provide an improvement over get and set methods by letting you use simple array syntax. Here is an example of how to declare a large `AnsiString` that extends over several lines:
    AnsiString S =

        "Easy is right. Begin right ";

        "And you are easy. "

        "Continue easy and you are right. "

        "The right way to go easy "

        "Is to forget the right way "

        "And forget that the going is easy.";
The `StripWords` function is used to peel off words from this quote one at a time, starting at the front:
    AnsiString StripWords(AnsiString &S, char Token)

    {

      AnsiString TokenStr(Token);

      AnsiString Temp1;

      AnsiString Temp2 = S + ` `;

      Temp1 = strtok(S.c_str(), TokenStr.c_str());

      Temp2 = strrev(Temp2.c_str());

      Temp2.SetLength(Temp2.Length() - (Temp1.Length() + 1));

      S = strrev(Temp2.c_str());

      return Temp1;

    }
There are two interesting things about this function. The first shows how to concatenate strings with the plus operator, and the second shows how to use standard C string functions on an `AnsiString`. Notice the bit of syntax that adds a space onto the end of the string passed to the function:
    AnsiString Temp2 = S + ` `;
You can always use the plus operator to append or prefix information to an `AnsiString`. This eliminates any need for you to use the `strcat` function, though `strcat` is a likely candidate for the routine inside the `AnsiString` implementation that actually performs the concatenation. NOTE: The reason I append a space onto the end of this string is to ensure that the `AnsiString` object that underlies this C string makes a unique copy of it. If I simply assign the two strings without changing them, the call to `strrev` or `strtok` will affect both strings! Note also that `AnsiString`s support the `+=` operator. Therefore you don't have to write `S = S + "Sam"`, but can write `S += "Sam"`. I do, however, use standard C functions to tokenize and reverse the strings:
    Temp1 = strtok(S.c_str(), TokenStr.c_str());

    Temp2 = strrev(Temp2.c_str());

    Temp2.SetLength(Temp2.Length() - (Temp1.Length() + 1));
What the function does here is not important. Just notice that I can get at the underlying `null`-terminated string with the `c_str()` method of the `AnsiString` class. Once I have access to the underlying string, I can pass it to any of the standard C functions such as `strrev`, `strcat`, `strtok`, and so on. To get the length of a string, call the `Length` method of the `AnsiString` class:
    int I = MyString.Length();
I have gone on at some length about the `AnsiString` class because it is used extensively throughout this book and throughout most BCB programs. The key fact to remember is that `AnsiString`s are compatible with the VCL. For instance, you can assign an `AnsiString` directly to a VCL control:
    AnsiString S("Doubting the filching age will steal his treasure");

    Edit1->Text = S;
You can also assign a regular C string to a VCL control, but that is because the VCL string is represented on the C++ side as an `AnsiString`, which can have its constructor called by a `null`-terminated string:
    char S[] = {"Till either gorge be stuffed or prey be gone"};

    Memo1->Text = S;
NOTE: This time the quote is from Shakespeare's Venus and Adonis, with this seemingly gruesome line appearing in the following context: `Till either gorge be stuffed or prey be gone Even so she kiss'd his brow, his cheek, his chin, And where she ends she doth anew begin.` The bard's point being, I suppose, that her appetites were large. In fact, you can take advantage of these constructors and assign an integer directly to a VCL control:
    Memo1->Text = 2;
This is considerably more freedom than the strongly typed Object Pascal language would ever give you liberty to pursue. ## Exploring SYSDEFS.H This chapter is largely about the places where C++ and the VCL are woven together. Most of the code that is used to accomplish this end is found in `SYSDEFS.H`. `SYSDEFS.H` is the place where the developers put most of the core system code needed to allow BCB to use the VCL native types. In particular, if there was some element of Object Pascal not supported by C++ that played a role in the VCL, solutions to that problem were mapped out in this file. The only major exception to this rule is `DSTRINGS.H`, where the `AnsiString` class is declared. NOTE: `SYSDEFS.H` is to some degree a testament to the power of the C++ language. It features classes and templates that emulate features of Object Pascal that Delphi relies on the compiler to implement. The advantage of having the compiler implement these features is that it is possible to pick and choose exactly what kind of syntax you want to use. Thus the elegance and simplicity of the Object Pascal language. On the other hand, the extraordinary richness and flexibility of the C++ object model is highlighted beautifully by the work done in `SYSDEFS.H`. The following classes appear in `SYSDEFS.H`:
    class __declspec(delphireturn) Currency : public CurrencyBase

    class __declspec(delphireturn) TDateTime : public TDateTimeBase

    class __declspec(delphiclass) TObject

    class TMetaClass

    class __declspec(delphireturn) Set

    class TVarArray

    class TVarData

    class TVarRec

    template<class T> class OpenArray

    class __declspec(delphireturn) Variant: public TVarData

    class AutoCmd

    class NamedParm

    class Procedure: public AutoCmd

    class Function: public AutoCmd

    class PropertySet: public AutoCmd

    class PropertyGet: public AutoCmd

    typedef class TMemoryManager *PMemoryManager;

    class THeapStatus;
Some of these classes, such as `TObject` and `TMetaClass`, have already been discussed at length. Other classes such as `Procedure`, `Function`, `PropertyGet`, and `PropertySet` are part of the guts of the BCB-VCL interface, and are not worth discussing in this context. But a few of these classes, notably `Set`, `Currency`, `TDataTime`, `Variant`, and `TMemoryManager` play an important role in standard BCB programming, and will therefore be covered in the next few pages. I will also take a look at `TVarRec` and `OpenArray`, because they play an important supporting role in the object model. ## Formatting Text In the next three sections, called `TDateTime`, `TCurrency`, and `OpenArray`s, I explore some of the ways you can format text before presenting it to the user. You should read through all three sections to get a feeling for some of the options supplied by BCB. Many tools for formatting text have been contributed by third-party VCL vendors. There are many sites on the Web that provide links to third-party toolmakers. To get started, visit the Link section of my Web site: `users.aol.com/charliecal`, or go to `www.borland.com`. ### TDateTime The VCL comes equipped with a number of functions for working with the current date or time, as shown by this excerpt from the online help:
`Date` | Returns the current date
`DateTimeToStr` | Converts a value from time format to a string
`DateTimeToString` | Converts a value from time format to a string
`DateToStr` | Converts a value from date format to a string
`DayOfWeek` | Returns the current day of the week
`DecodeDate` | Decodes the specified date
`DecodeTime` | Decodes the specifies time
`EncodeDate` | Returns values specified in date format
`EncodeTime` | Returns values specified in time format
`FormatDateTime` | Formats a date and time using the specified format
`Now` | Returns the current date and time
`StrToDate` | Coverts a string to a date format
`StrToDateTime` | Converts a string to a date/time format
`StrToTime` | Converts a string to a time format
`Time` | Returns the current time
`TimeToStr` | Converts a time format to a string
There is also a `TDateTimeField` that is used in database programming. Many of these functions work with an object type called `TDateTime` that is found in the `SYSDEFS.H` unit. Most of the rest of this section is dedicated to exploring the uses of the `TDateTime` type. This type exists in order to provide compatibility with the VCL routines listed at the beginning of this section. The following method shows two different ways of outputting the current date:
    void __fastcall TForm1::CurrentDate1Click(TObject *Sender)

    {

      TDateTime Date1, Date2 = Now();

      AnsiString S;

      DateTimeToString(S, "dddd, mmmm dd, yyyy", Date1.CurrentDate());

      S += "\r" + Date2.FormatString("dddd, mmmm dd, yyyy");

      ShowMessage(S);

    }
The code shown in the `CurrentDate1Click` method outputs the following text inside a `RichEdit` control:
    Tuesday, January 07, 1997

    Tuesday, January 07, 1997
NOTE: The `TRichEdit` control from the Win95 page of the Component Palette provides supports for the RTF format. There is no set limit on the amount of text you can display in a `TRichEdit` control, and it supports the use of multiple fonts and colors inside a single control. There are also routines for saving the loading and saving the contents of the control, and for printing. I initialize the first of the two `TDateTime` objects with the default constructor, which automatically sets the date to Saturday, December 30, 1899. Then set asks this object to retrieve the current date (not the default date), which it passes to me in the form of a `TDateTime` object:
    static TDateTime __fastcall CurrentDate();
A raw `TDateTime` object is obviously not something I can show to the user, so I use the VCL `DateTimeToString` routine to convert it into a string:
    DateTimeToString(S, "dddd, mmmm dd, yyyy", Date1.CurrentDate());
This routine takes a string in the first parameter, a format string in the second parameter, and a `TDateTime` record in the third parameter. NOTE: If you look in `SYSDEFS.H`, you will see that `TDateTime` is declared `delphireturn`. That is because this object needs to conform to the expectations of VCL routines such as `DateTimeToString`. In other words, this is a classic example of what use the BCB team made of `delphireturn`. The second `TDateTime` object shown in this example is set equal to the current date during its construction:
    TDateTime Date2(Now());
Notice that I pass the VCL routine called `Now` to the `TDateTime` constructor. `Now` returns a variable of type `TDateTime` that is initialized to the current date and time. You can then use the `FormatString` method of the `TDateTime` object to retrieve the current string:
    S += "\n" + Date2.FormatString("dddd, mmmm dd, yyyy");
The `FormatString` method takes the same type of format string passed to `DateTimeToString`. Format strings are documented in the online help, but the basic idea behind them is that if you pass in two letters, you get a number back; pass in three letters, and you get an abbreviation back; and pass in four letters, and you get a whole word back:
    dd => 01

    ddd => Sun

    dddd => Sunday
The following method displays the current time in a specified format:
    void __fastcall TForm1::CurrentTime1Click(TObject *Sender)

    {

      TDateTime Date(Now());

      RichEdit1->Text = Date.FormatString("h:nn:ss am/PM");

    }
The result will look something like this:
    12:27:56 PM
In this case, the `PM` is in large letters because I wrote it that way in the format specifier. Had I written `am/pm`, the resulting string would have looked like this: `12:27:56 pm`. The rest of the format specifiers works like this:
    h => No leading zero

    hh => Prefix a leading zero
In short, if you pass in one letter, you get back a string with no leading zero; if you pass in two, a leading zero will be added automatically. Notice that you pass in an `n` to specify the format for minutes. This is because `m` has already been used for months. Here is a table listing the various specifiers you can use:
Format specifier | Item
`s` | Seconds
`m` | Minutes
`h` | Hour
`d` | Day
`m` | Month
`y` | Year
`am/pm` | Format for time
`c` | Uses `ShortDateFormat` and `LongTimeFormat`
`t` | Uses `ShortTimeFormat`
`tt` | Uses `LongTimeFormat`
`ddddd` | Display date using `ShortDateFormat`
`dddddd` | Display date using `LongDateFormat`
The various date and time formats shown in the last items will be explained in just one moment. The `DateTimeString`., `DateString`, and `TimeString` methods of the `TDateTime` object do not require that you provide format specifiers. Here, for instance, is an example of how to use the `DateTimeString` method:
    void __fastcall TForm1::DateandTime1Click(TObject *Sender)

    {

      TDateTime Date(Now());

      RichEdit1->Lines->Add(Date.DateTimeString());
    }
On my system, the code shown here produces the following result:
    1/7/97 12:31:24 PM
The format used in this case is global to the system. You can change these settings by working with a series of global variables found in `SYSUTILS.HPP`:
    extern System::AnsiString CurrencyString;

    extern unsigned char CurrencyFormat;

    extern unsigned char NegCurrFormat;

    extern char ThousandSeparator;

    extern char DecimalSeparator;

    extern unsigned char CurrencyDecimals;

    extern char DateSeparator;

    extern System::AnsiString ShortDateFormat;

    extern System::AnsiString LongDateFormat;

    extern char TimeSeparator;

    extern System::AnsiString TimeAMString;

    extern System::AnsiString TimePMString;

    extern System::AnsiString ShortTimeFormat;

    extern System::AnsiString LongTimeFormat;

    extern System::AnsiString ShortMonthNames[12];

    extern System::AnsiString LongMonthNames[12];

    extern System::AnsiString ShortDayNames[7];
    extern System::AnsiString LongDayNames[7];
On my system, these values are preset as follows:
    CurrencyString: $

    CurrencyFormat: 0

    NegCurrFormat: 0

    ThousandSeparator: ,

    DecimalSeparator: .

    CurrencyDecimals: 2

    DateSeparator: /

    ShortDateFormat: M/d/yy

    LongDateFormat: dddd, MMMM dd, yyyy

    TimeSeparator: :

    TimeAMString: AM

    TimePMString: PM

    ShortTimeFormat: h:mm AMPM

    LongTimeFormat: h:mm:ss AMPM

    ShortMonthNames: Jan

    ShortMonthNames: Feb

    ShortMonthNames: Mar

    ShortMonthNames: Apr

    ShortMonthNames: May

    ShortMonthNames: Jun

    ShortMonthNames: Jul

    ShortMonthNames: Aug

    ShortMonthNames: Sep

    ShortMonthNames: Oct

    ShortMonthNames: Nov

    ShortMonthNames: Dec

    LongMonthNames: January

    LongMonthNames: February

    LongMonthNames: March

    LongMonthNames: April

    LongMonthNames: May

    LongMonthNames: June

    LongMonthNames: July

    LongMonthNames: August

    LongMonthNames: September

    LongMonthNames: October

    LongMonthNames: November

    LongMonthNames: December

    ShortDayNames: Sun

    ShortDayNames: Mon

    ShortDayNames: Tue

    ShortDayNames: Wed

    ShortDayNames: Thu

    ShortDayNames: Fri

    ShortDayNames: Sat

    LongDayNames: Sunday

    LongDayNames: Monday

    LongDayNames: Tuesday

    LongDayNames: Wednesday

    LongDayNames: Thursday

    LongDayNames: Friday

    LongDayNames: Saturday
For instance, the following code changes the nature of the current `ShortDateFormatString`:
    void __fastcall TForm1::SetShortDateFormattoMMMMDDDDYYYY1Click(TObject *Sender)

    {

      RichEdit1->Text = Now();

      ShortDateFormat = "MMMM/DDDD/YYYY";

      RichEdit1->Lines->Add(Now());
    }
The text displayed by calling this function is as follows:
    1/7/97 1:30:21 PM

    January/Tuesday/1997 1:30:21 PM
The first block of text shows the default behavior, and the second block shows what happened after I made a few subtle changes to the system. The system initializes the date and time strings to the choices you make in Windows. You can see the current Windows settings by calling `GetLocaleInfo`. Changes you make are written to the system registry if you send a `WM_INICHANGE` message to your own nonconsole mode application. The following lines of code show how you can compare two times using the greater than operator:
    void __fastcall TForm1::SetTimeOne1Click(TObject *Sender)

    {

      FTimeOne = Now();

      RichEdit1->Text = FTimeOne.TimeString();

    }

    void __fastcall TForm1::SetTimeTwo1Click(TObject *Sender)

    {

      FTimeTwo = Now();

      RichEdit1->Lines->Add(FTimeTwo.TimeString());

    }

    void __fastcall TForm1::CompareOnetoTwo1Click(TObject *Sender)

    {

      AnsiString S;

      if (FTimeOne > FTimeTwo)

        S = FTimeOne.TimeString() + " > " + FTimeTwo.TimeString();

      else

        S = FTimeTwo.TimeString() + " > " + FTimeOne.TimeString();

      RichEdit1->Lines->Add(S);
    }
The first method shown here sets a global object called `TimeOne` to the current time. The second method sets a second global object to the current time. After calling the two functions at a two-second interval, you can end up with the objects initialized to two different times:
    2:10:29 PM

    2:10:31 PM
You can then use the third function to compare them using the `>` operator:
    2:10:31 PM > 2:10:29 PM
You can also use the `++` operator on the current time to increment the day by one:
    void __fastcall TForm1::CompareTwotoOne1Click(TObject *Sender)

    {

      int i;

      RichEdit1->Lines->Add(FTimeOne.DateTimeString());

      FTimeOne++;

      RichEdit1->Lines->Add(FTimeOne.DateTimeString());

    }
Here is the output in the `RichEdit` control after a run off all four functions:
    2:13:03 PM

    2:13:05 PM

    2:13:05 PM > 2:13:03 PM    // First call to compare

    1/7/97 2:13:03 PM

    1/8/97 2:13:03 PM

    2:13:03 PM > 2:13:05 PM    // Second call to compare
As you can see, calling the `++` operator incremented the day by one. After incrementing the values, a second call to the compare function showed that `FTimeOne` is now larger than `FTimeTwo`. Even though it is still two seconds smaller than date two, it is now a day later, and hence larger. This should give you some sense of what you can do with the `TDateTime` type. This has not been an exhaustive investigation of what can be done, but if you now open up `SysDefs.h`, you should have no trouble following the drift of the declaration for the other methods in the `TDateTime` object. The code samples shown in this section are from a program found on disk called, in a flight of poetic fancy, `DateTime1`. ### TCurrency I will now spend a few minutes looking at `TCurrency`. After the rather lengthy investigation of `TDateTime` that you just saw, there should not be much need to examine this object in-depth, because it follows the same general patterns of logic you saw in the previous section. When following this discussion, remember that the primary reason the type exists is for compatibility with the VCL. In particular, the `TCurrency` type, like the `TDateTime` type, is used in database programming. For instance, there is a `TCurrencyField` and a `TDateTimeField` available for database programmers. The principles behind the field types are examined in detail throughout the lengthy database section of this book, Chapters 8 through 18, and particularly in Chapter 11, "Working with Field Objects." The `Currency` type is a wrapper around the built in `__int64` type. The compiler probably will not support assigning large numbers directly to a variable of type `Currency`:
    Currency C = 5000000000000; // This probably won't work
You can, however, pass in a string that holds a large number. Consider the following method:
    Currency C = void __fastcall TForm1::Button1Click(TObject *Sender)

    {

      Currency C("500000000000000");

      AnsiString S = C;

      Edit1->Text = S;

      Edit2->Text = Format("%m", OPENARRAY(TVarRec, (C)));
    }
This method initializes a variable of type currency to a large number with a string. Most of the time large numbers will be entered by the user in an edit control, so this is a reasonable way to proceed. Once you have an instance of a `Currency` type, you can display it directly to the user or assign it to a `TCurrencyField` from a database table. Notice that you can assign a string directly to a `Currency` field, and vice versa. When translating a currency type to a string, the result does not produce a formatted result string. Instead, you see a plain number:
    500000000000000
If you want to display the string with proper formatting, use the `Format` function, as shown in the `Button1Click` method:
    $500,000,000,000,000.00
I will describe the `Format` function, and `OpenArray`s, in the next section of this chapter, called "Working with `OpenArray`s." Note that some of the database controls will automatically display a currency type with formatting, depending in part on their attributes and the contents of the Data Dictionary. The currency type will handle numbers in the following range:
    -922337203685477.5808..922337203685477.5807
That is, it can handle between 19 and 20 digits. There are many operators in the `Currency` class for performing mathematical operations. For instance, the following syntax is valid:
    Currency C1 = 25000, C2 = 5000, C3;

    C1 += C2;

    C1 = C2 / 9;

    C3 = (C1 % C2);

    C3 = (C1 + C2) / C1 + (C1 % C2);
It's interesting to note that these operations are performed on objects, and not on simple types. This is an excellent example of the power of C++ and the amazing things you can do with operator overloading. If you are not used to C++, you should spend a few moments contemplating the fact that `C1`, `C2`, and `C3` are objects, with methods and functions, and not just simple built-in types like integers or floats. You should open up `SysDefs.h` to see a list of all the supported syntax used by the `Currency` object. ## MaskEdits and Other Issues The native VCL `TMaskEdit` control deserves at least a few sentences of comment during this discussion of formatting strings. This component is a descendant of `TEdit` that enables you to control the kinds of characters that are entered into the control. The key to the `TMaskEdit` component is the `EditMask` property, which enables you to enter a string that uses several special characters to define what the user can legally enter into the edit area. There is a property editor associated with the `EditMask` property. In this editor, you can find a number of default masks, as shown in Figure 3.1. However, on many occasions, none of these masks will suit your purpose. Figure 3.1. The property editor for the `EditMask` property. I could, for instance, enter the following string as an `EditMask`:
    ######;0;_
The purpose of this string is to ensure that the user can enter only numeric values. In particular, these numeric values represent the number of widgets that the user wants to sell. To understand the `EditMask` property, you need to study the entry associated with it in the online help. Here, you see all the characters that can be used to define a mask, along with a description of the effects associated with each character. I quote most of this list later in this section. In the online help for the `EditMask` property, you will find that a pound sign (`#`) enables you to enter only numbers, spaces, and plus and minus characters. Notice, however, that there is also a `0` character, which requires that you enter a number in each location marked with that character. The question, then, is which special character should you use: `#` or `0`? In some cases, the `0` character is not what you want, because it forces the user to enter values. For instance, the following code forces the user to enter a six-digit number, one for each of the zeroes you place in the mask:
    000000;0;_
The preceding mask would enable you to enter the number `123456`, but it would reject `123`. If you want to give the user the freedom to enter a number of any size up to `999,999`, you should use the `#` character rather than the `0` character. One way to sum this matter up is as follows: The `0` character means that the user has to fill in that place with a number, while the `#` character enables the user to fill in that space with either a number or a blank space. The zero that appears after the semicolon in the previous string specifies that the mask entered is not saved as part of the data. If I had placed a `1` here, the mask would have been saved. In this particular case, there are no mask characters to either save or discard, so it doesn't matter what I placed in this location. The phone mask, shown previously in Figure 3.1, contains two parentheses that would be affected by this value. Finally, the very end of the previous mask includes an underscore. This value is used to specify what will be used to designate the space character. Notice that each field of the mask is separated from the last by a semicolon. Each mask consists of three fields, which were described earlier. The `MaskEdit` component is available from the Additional page of the Component palette. Notice that you can click a button in the `EditMask` dialog found in the `EditMask` property editor in order to load country-specific strings. NOTE: The following lists format specifiers you can use in the `TMaskEdit` control: `!` If an `!` character appears in the mask, leading blanks don't appear in the data. If an `!` character is not present, trailing blanks don't appear in the data. `>` If a `>` character appears in the mask, all characters that follow are in uppercase until the end of the mask or until a `<` character is encountered. `<` If a `<` character appears in the mask, all characters that follow are in lowercase until the end of the mask or until a `>` character is encountered. `<>` If these two characters appear together in a mask, no case checking is done and the data is formatted with the case the user uses to enter the data. `\` The character that follows a `\` character is a literal character. Use this character when you want to allow any of the mask special characters as a literal in the data. `L` The `L` character requires only an alphabetic character only in this position. For the US, this is A-Z, a-z. `l` The `l` character permits only an alphabetic character in this position, but doesn't require it. `A` The `A` character requires an alphanumeric character only in this position. For the US, this is A-Z, a-z, and 0-9. `a` The `a` character permits an alphanumeric character in this position, but doesn't require it. `C` The `C` character requires a character in this position. `c` The `c` character permits a character in this position, but doesn't require it. `0` The `0` character requires a numeric character only in this position. `9` The `9` character permits a numeric character in this position, but doesn't require it. `#` The `#` character permits a numeric character or a plus or minus sign in this position, but doesn't require it. `:` The `:` character is used to separate hours, minutes, and seconds in times. If the character that separates hours, minutes, and seconds is different in the International settings of the Control Panel utility on your computer system, that character is used instead of `:`. `/` The `/` character is used to separate months, days, and years in dates. If the character that separates months, days, and years is different in the International settings of the Control Panel utility on your computer system, that character is used instead of `/`. `;` The `;` character is used to separate masks. `_` The `_` character automatically inserts a blank the edit box. When the user enters characters in the field, the cursor skips the blank character. When using the `EditMask` property editor, you can change the character used to represent blanks. You can also change this value programmatically. See the following table. Remember that many of the database objects such as the `TDateTime` field provide automatic formatting for you. This is also an area where you might consider turning to third-party products. For instance, Turbo Power Software has an excellent library called Orpheus that provides many fine controls and routines for automatically formatting strings. You should, however, explore the market thoroughly, because there are many fine products out there for handling this type of problem. In particular, many controls are found on the Web. You can visit my Web site to find links to sites that specialize in components. (`users.aol.com/charliecal`). ## Working with OpenArrays The VCL supports a concept called an array of `const`. This type will enable you to pass in a variable number of parameters. Think for a moment of the `sprintf` function:
    int sprintf(char *buffer, const char *format[, argument, ...]);
The last argument of this function can contain multiple parameters. `OpenArray`s provide the same functionality in Object Pascal. In short, they enable you to pass a variable number of parameters to a function. Here is an Object Pascal code segment declared to accept an array of `const`:
    function Format(const Format: string; const Args: array of const): string;
The `Format` function acts almost exactly like `sprintf`. Its first parameter contains a string with various format specifiers in it, and its second parameter consists of an array containing multiple values to be formatted. The format specifiers used by `Format` are essentially the same as those you would use in `sprintf`. After all, the whole point of adding the function to the Object Pascal language was simply to duplicate the functionality of `sprintf` inside Object Pascal. Here is the way a call to `Format` looks in Object Pascal:
    var

      S, Name: string;

      Age: Integer;

    begin

      Name = GetName;

      Age = GetAge;

      S :=  Format("My name is %s and I am %d years old", [Name, Age]);

    end;
All this is good and well, but you might object that C++ already has support for this kind of syntax through `sprintf`. That is correct, but you will find many VCL database routines that use arrays of `const` for various purposes. There are no standard C++ equivalents of these routines, as they exist only in the VCL. In other words, the C++ and Object Pascal implementations of this functionality differ in their details, even though the interface to the user is similar. As a result, special C++ classes need to be created to duplicate this built-in Object Pascal type. While you may or may not find the `Format` routine itself useful, you will definitely need to know about arrays of `const` if you want to work with the VCL, and particularly if you want to do any database programming. For instance, the following database routines all use arrays of `const`: `FinkKey`, `FindNearest`, `SetRange`, `AddRecord`, `SetKeyFields`, `AppendRecord`, `InsertRecord`, `SetFields`, `AssignValue`, and `DBErrorFmt`. Clearly, this is a subject that you need to understand. Here is the declaration for the `Format` function as it appears in `SYSUTILS.HPP`:
    extern System::AnsiString __fastcall Format(const System::AnsiString Format,

      const System::TVarRec *Args, const int Args_Size);
As you can see, this function takes not two, but three parameters. You will not, however, pass all three parameters into this function, nor will you pass them into any of the database routines shown previously. Instead, you use a macro called `OPENARRAY`, which enables you to call VCL functions that use arrays of `const` with a reasonable degree of ease. NOTE: As I am sure you have noticed already, this particular subject is not exactly the garden spot of C++Builder. We are definitely in the low-rent district right now, and so perhaps a few more words of explanation are necessary. Object Pascal originally had no support for functions that took a variable array of parameters. As the spec for Delphi developed, it became clear that there had to be a solution to this problem. The language needed to support functions that took a varying array of parameters because various database calls demanded this functionality. In particular, routines that dealt with keyed fields needed varying numbers of parameters depending on the number of fields present in a composite key. An `array of const` was the solution the Object Pascal team came up with for this problem. On the Delphi side, this is a elegant solution that enables you to write simple, easy-to-read code. However, this is not the same solution that the C and C++ languages used when resolving a similar problem. As a result, arrays of `const` are implemented in an entirely different manner than either the `variadic` arguments such as you find in `sprintf`, or the standard C++ practice of function overloading. There was, in short, no common ground between the two languages when it came to this subject. Hence you find your self wandering down this dark alley, where `OpenArray`s meet the array of `const`. I won't make myself look foolish by trying to claim that the solution found here is elegant, but it is usable. Given the nature of the problem the BCB team had thrust upon them, the solution seems reasonable to me. I also do not feel that this particular low-rent district is typical of BCB neighborhoods. I love BCB components, properties, and events. These are areas where the tool really shines. Open arrays, on the other hand, are at best nothing more than a satisfactory solution to a difficult problem. One important point to note about the BCB environment, however, is that you can use function overloading in some cases, `OPENARRAYS` in other cases, or switch to Object Pascal code and use elegant and concise solution provided by an `array of const`. This environment provides a rich set of tools from which you can pick and choose. Because you have access to the tools available in two different languages, there is no other programming environment on the market that even comes close to the richness of features found in BCB. Here is a routine that uses both open arrays and `sprintf` to solve the same problem:
    void __fastcall TForm1::Button1Click(TObject *Sender)

    {

      char S[150];

      if (MoreInput->ShowModal() == mrOk)

      {

        sprintf(S, "Hello, my name is %s, and I'm %d years old.",

         MoreInput->Name, MoreInput->Age);

        Edit1->Text = S;

        Edit2->Text = Format("Hello, my name is %s, and I'm %d years old.",

         OPENARRAY(TVarRec, (MoreInput->Name, MoreInput->Age)));

      }

    }
In showing your comparative examples of `sprintf` and `Format`, this function makes use of a second form called `TMoreInput`. I will discuss this form in the next section of the chapter. For now, however, I will forgo discussing multiform projects, and will concentrate instead on using `OpenArray`s. As you can see, it doesn't really take any more code to use `Format` and `OPENARRAY` than it does to use `sprintf`. In fact, both techniques have their disadvantages. The `sprintf` method requires you to declare a temporary variable, the `Format` method gives you a good dose of the wordy `OPENARRAY` macro. However, neither technique is particularly difficult to implement. When using `OPENARRAY`, you usually pass `TVarRec` as the first argument of the macro, and then pass a comma-delimited set of variables in the second argument. The entire second argument should be set off by parentheses. Here are a few rather artificial examples of how to use the macro:
    OPENARRAY(TVarRec, (1))

    OPENARRAY(TVarRec, (1, 2))

    OPENARRAY(TVarRec, (1, 2, 3))
And so on, up to, but not beyond, `18`. The point is that you pass the variables you want to have processed in the second argument to the macro. You can pass any type in this section, because the macro itself doesn't care. The method that is using the macro may not be so forgiving, however, so you need to put some thought into the code you write. For instance, `Format` takes only certain types of parameters, and there would be no point in passing something to `OPENARRAY` that the `Format` function could not process. The same holds true of `sprintf`. There would be no point in passing the wrong type of parameter to it, because the format specifiers handle only certain types. The `OPENARRAY` macro itself is very simple:
    #define OPENARRAY(type, values) \

       OpenArray<type>values, OpenArrayCount<type>values.GetHigh()
As you can see, it takes two separate object templates to make the array work. (In fact, `TVarRec` is a third object, so it takes three objects in all to bring this business home for dinner.) If you are interested, you can open up `SysDefs.h` and see how this technology is implemented. For the purposes of this book, however, I will simply say that this is one of those cases where you should "pay no attention to the man behind the curtain." I just let the macro do its work and concentrate instead on the parts of the program that are under my jurisdiction. That is all I'm going to say about `OpenArray`s. As I conceded earlier, this is not really the garden spot of BCB programming. However, the code I've shown you does get the job done. In particular, the point of this `OpenArray` business is that it enables you to pass a variant number of parameters to a function. This is a pretty slick trick in itself, and some programmers will probably be able to find occasions when they can use this technology for their own purposes. Its main value, however, is simply that it enables you to use the parts of the VCL that are expecting an `array of const`. ## Using Two Forms in One Program The sample function shown above called `Button1Click` has a line in it where a second form is launched:
    if (MoreInput->ShowModal() == mrOk)
The program uses this second form to retrieve the name and age input from the user. Popping up a form to get information from a user is a common task in BCB, so I should perhaps take a moment to explain how it works. To get started, you should use the File menu, or some other tool, to create a second form for your project. Save it into the same directory where your current project is located. Add two edit controls labeled `Name` and `Age` to the second form, and place two `TBitBtns` on the form, as shown in Figure 3.2. Use the `Kind` property of the `BitBtns` to make one an OK button and the second a Cancel button. Notice that the `ModalResult` property of the OK `TBitBtn` is automatically set to `mrOk`, and the `ModalResult` property of the Cancel `TBitBtn` is automatically set to `mrCancel`. Figure 3.2.The form for the `TMoreInput` dialog has two labels, two edit controls, and two `TBitBtns`. Now create two properties that users of the form can use when they need to access the input from the user:
    class TMoreInput : public TForm

    {

      // Code omitted here

    private:

      AnsiString FName;

      int FAge;

    public:

      virtual __fastcall TMoreInput(TComponent* Owner);

      __property int Age={read=FAge, write=FAge};

      __property AnsiString Name={read=FName, write=FName};

    };
As you can see, the `Age` and `Name` properties front for two `private` variables of the object. These variable are assigned to the user's input if the user presses the OK button:
    void __fastcall TMoreInput::OkBtnClick(TObject *Sender)

    {

      Name = Edit1->Text;

      Age = Edit2->Text.ToInt();
    }
It is now time to go full circle and look back at the stripped-down version of the function that makes use of this dialog:
    void __fastcall TForm1::Button1Click(TObject *Sender)

    {

      if (MoreInput->ShowModal() == mrOk)

      {

        Edit2->Text = Format("Hello, my name is %s, and I'm %d years old.",

         OPENARRAY(TVarRec, (MoreInput->Name, MoreInput->Age)));

      }
    }
The `Button1Click` method calls the `TForm` `ShowModal` method to launch the dialog. If the user presses the OK button, the input is retrieved from the `TMoreInput` dialog through the officially designated properties. This enables you to use the private data of `TMoreInput` without forcing `TMoreInput` to refrain from ever changing its implementation. For instance, `TMoreInput` could someday use a `struct` that contains both the `Name` and `Age` fields, but could continue to give users of the form access to data through the `Name` and `Age` variables. If you are interested in this program, you can find it on disk in the `Chap02` directory as a file called `OpenArrays1`. The program itself is simple, but it gives a good illustration of how to use a second dialog to retrieve information from the user. This is a common task that will see many variations run on it in different parts of this book. ## Working with the Set Object Sets are used widely in BCB. Here for instance, is the `MsgDialog` routine, which is called frequently but requires some knowledge of sets before you can use it correctly:
    AnsiString S("While Lust is in his pride, no exclamation \n"

                 "Can curb his heat or rein his rash desire.");

    MessageDlg(S, mtInformation, TMsgDlgButtons() << mbOK, 0);
The VCL makes heavy use of sets, so there are a number of places in standard BCB database or interface code where you will need to take advantage of the syntax you see here. The goal of the next few pages of this chapter is to explore the BCB Set class and reveal its inner workings. Sets are easy to understand if you just take a few minutes to absorb their syntax. This is, however, one of those subjects that you have to master if you want to use BCB. In fact, you will find many parts of BCB cumbersome if you don't understand this template class. Here is a "pseudo template" for the header of the set class designed to help you see how these sets are structured:
    Set<Type, MinimumValue, MaximumValue>
More precisely, here is the more formal header declaration from `SysDefs.h`:
    template<class T, unsigned char minEl, unsigned char maxEl>
To declare a set, you write the word `Set` followed by an open bracket, the type of your set, and its minimum and maximum values. For instance, if you want to create a set of all small letters, you would write
    Set<char, `a', `z'> SmallLetters;
To create the set of all numbers between 0 and 9, you might write
    Set<int, 0, 9> SmallNumbers;
In the first case, `MySet` does not consist of the letters `a` and `z`, but of `a`, `z`, and all the letters between them. In other words, the letter `a` is the smallest value in the set and the letter `z` is the maximum value in the set, as shown previously in the formal declaration for the `template` class. Both `SmallLetters` and `SmallNumbers` are declarations of objects. Often, you don't want to create a new object, but create a new object type with the `typedef` keyword:
    typedef Set<int, 0, 9> TSmallNumbers;
Now you have a type you can work with, and can therefore declare separate instances of this type:
    TSmallNumbers SmallNumbers1;

    TSmallNumbers SmallNumbers2;
> The point here is that the first numeric set declared previously, the one called `SmallNumbers`, is an instance of an object, while `TSmallNumbers` is the declaration for a type. NOTE: I'm going to break a rule of this book and spend a few moments on standard C syntax. In particular, I'm going to look at `typedef`s, because this is an important and easily misunderstood part of the language. The `typedef` keyword enables you to declare a type within a particular scope. Unfortunately, the `#define` directive performs a function similar to the `typedef` keyword, even though the two pieces of syntax have different ways of implementing the result. For instance, the following two lines have the same effect on your code:
>     typedef float REAL;

>     #define float REAL
One asks the compiler to do its work for it, while the second asks the preprocessor to do the work. The result, however, is similar. That is, they give you a new "type" to work with called `REAL`. I try to keep some order in my code by always using `typedef` to declare types, while I generally use `#define` only to declare constants. No one is perfect, and I probably break that rule from time to time, but I try to follow it with some regularity. A `typedef` has effect only within a particular scope. I generally declare types in the header for a unit, unless I want to limit the scope of the type to a particular method or function, in which case I declare the type inside that method or function. I will not go into this subject any further in this book, nor is the discussion included here meant to be exhaustive. If you want additional information on the `typedef` keyword, you should turn to a primer on C++. For this book all you need to know is that `typedef`s provide a way of declaring your own types within a particular scope. I never use it for any other purpose, and I try never to use any other technique for declaring types. Now that you know the basic facts about sets, it's time to look at some programs that give them a workout. These are important examples, so I will feature them in their own section of the chapter. ### Two Sample Programs for Working with Sets The sample program shown in Listings 3.3 and 3.4, called NumberSets, gives you a look at the basic syntax for creating sets. It is followed by a second sample program, called `SetBasics`, that shows how to create the union, intersection, and difference of two sets. NOTE: The Set sample programs used in this book originally included some sample components that are found in the `Examples` directory that ships with BCB. These components were found in Delphi on a page called Samples, but are not installed by default in BCB. If you go into the `Examples\Controls` directory, you will find an explanation of how to install these components. In particular, the spin edit control can be a useful tool to use in this kind of program. Check the CD that accompanies this book for an update on this issue and how it affects these programs. #### Listing 3.3. The header for the NumberSets program.
    //--------------------------------------------------------------------------

    #ifndef MainH

    #define MainH

    //--------------------------------------------------------------------------

    #include <vcl\Classes.hpp>

    #include <vcl\Controls.hpp>

    #include <vcl\StdCtrls.hpp>

    #include <vcl\Forms.hpp>

    #include <vcl\Spin.hpp>

    //--------------------------------------------------------------------------

    typedef  Set<int, 0, 9> TSmallNum;

    class TForm1 : public TForm

    {

    __published:

      TButton *AddToSetABtn;

      TListBox *ListBox1;

      TSpinEdit *SpinEdit1;

      TButton *RemoveFromSetBtn;

      void __fastcall AddToSetABtnClick(TObject *Sender);

      void __fastcall RemoveFromSetBtnClick(TObject *Sender);

    private:

      TSmallNum NumSet;

      void __fastcall ShowSet(TSmallNum ANumSet, int ListBoxNum);

    public:

      virtual __fastcall TForm1(TComponent* Owner);

    };

    //--------------------------------------------------------------------------

    extern TForm1 *Form1;

    //--------------------------------------------------------------------------
`#endif` #### Listing 3.4. The main form for the NumberSets program.
    #include <vcl\vcl.h>

    #pragma hdrstop

    #include "Main.h"

    #pragma resource "*.dfm"

    TForm1 *Form1;

    __fastcall TForm1::TForm1(TComponent* Owner)

      : TForm(Owner)

    {

    }

    void __fastcall TForm1::ShowSet(TSmallNum ASmallNum, int ListBoxNum)

    {

      AnsiString S("Set <");

      for (int i = 0; i < 275; i++)

      {

        if (ASmallNum.Contains(i))

          S += "`" + AnsiString(i) + "`,";

      }

      S.SetLength(S.Length() - 1);

      S += ">";

      if (S.Length() == 5)

        S = "NULL Set";

      switch (ListBoxNum)

      {

        case 1:

          ListBox1->Items->Add(S);

          break;

    	default:

          ShowMessage("Error specifying listbox");

      }

    }

    void __fastcall TForm1::AddToSetABtnClick(TObject *Sender)

    {

      int i = SpinEdit1->Text.ToInt();

      NumSet << i;

      ShowSet(NumSet, 1);

    }

    void __fastcall TForm1::RemoveFromSetBtnClick(TObject *Sender)

    {

      int i = SpinEdit1->Text.ToInt();

      NumSet >> i;

      ShowSet(NumSet, 1);
`}` `` `NumberSet` works with a simple set containing the numbers between 0 and 9:
    typedef  Set<int, 0, 9> TSmallNum;

    TSmallNum NumSet;
The main function of the program is to show how to move items in and out of a set. The `AddToSetABtnClick` method retrieves the number the user places in a `TSpinEdit` control:
    int i = SpinEdit1->Text.ToInt();
It then uses the `<<` operator to insert the new number into the set:
    NumSet << i;
A similar method shows how to move information out of the set:
    int i = SpinEdit1->Text.ToInt();
    NumSet >> i;
The most complicated code in the program involves a method called `ShowSet` that creates a picture of the set and shows it to the user. The heart of the `ShowSet` method uses the `Contains` method of BCB's `Set` class to see if a particular element is contained in the set:
    if (ASmallNum.Contains(i))
`Contains` returns `True` if the element is part of the set, and it returns `False` if the element is not in the set. The results of this effort are shown to the user in a `TListBox`, as illustrated in Figure 3.3. Figure 3.3.The NumberSet program creates a visual image of a set so you can get an accurate feeling for how sets work. The SetBasics program takes the principles used in the NumberSet example and pushes them a little further so you can get a clear sense of what it means to create the intersection, union, or difference of two sets. (See Figure 3.4.) The code for the program is shown in Listing 3.5 and 3.6. Figure 3.4.The SetBasics program shows how to find the union, difference, or intersection of two sets. #### Listing 3.5. The header for the SetBasics program.
    //--------------------------------------------------------------------------

    #ifndef MainH

    #define MainH

    //--------------------------------------------------------------------------

    #include <vcl\Classes.hpp>

    #include <vcl\Controls.hpp>

    #include <vcl\StdCtrls.hpp>

    #include <vcl\Forms.hpp>

    #include <vcl\Menus.hpp>

    //--------------------------------------------------------------------------

    typedef Set <char, `A', `z'> TLetterSet;

    class TForm1 : public TForm

    {

    __published:

      TEdit *Edit1;

      TButton *AddToSetABtn;

      TListBox *ListBox1;

      TButton *AddToSetBBtn;

      TListBox *ListBox2;

      TListBox *ListBox3;

      TMainMenu *MainMenu1;

      TMenuItem *Options1;

      TMenuItem *Union1;

      TMenuItem *Intersection1;

      TMenuItem *Difference1;

      void __fastcall AddToSetABtnClick(TObject *Sender);

      void __fastcall AddToSetBBtnClick(TObject *Sender);

      void __fastcall Union1Click(TObject *Sender);

      void __fastcall Intersection1Click(TObject *Sender);

      void __fastcall Difference1Click(TObject *Sender);

    private:

      TLetterSet LetterSetA;

      TLetterSet LetterSetB;

      void __fastcall ShowSet(TLetterSet ALetterSet, int ListBoxNum);

    public:

      virtual __fastcall TForm1(TComponent* Owner);

    };

    //--------------------------------------------------------------------------

    extern TForm1 *Form1;

    //--------------------------------------------------------------------------
`#endif` #### Listing 3.6. The main form for the SetBasics program.
    #include <vcl\vcl.h>

    #pragma hdrstop

    #include "Main.h"

    #pragma resource "*.dfm"

    TForm1 *Form1;

    __fastcall TForm1::TForm1(TComponent* Owner)

        : TForm(Owner)

    {

    }

    void __fastcall TForm1::ShowSet(TLetterSet ALetterSet, int ListBoxNum)

    {

      AnsiString S("Set <");

      for (int i = 0; i < 275; i++)

      {

        if (ALetterSet.Contains(char(i)))

          S += "`" + AnsiString(char(i)) + "`,";

      }

      S.SetLength(S.Length() - 1);

      S += ">";

      if (S.Length() == 5)

        S = "NULL Set";

      switch (ListBoxNum)

      {

        case 1: ListBox1->Items->Add(S); break;

        case 2: ListBox2->Items->Add(S); break;

        case 3: ListBox3->Items->Add(S); break;

      default:

        ShowMessage("Error specifying listbox");

      }

    }

    void __fastcall TForm1::AddToSetABtnClick(TObject *Sender)

    {

      AnsiString S(Edit1->Text);

      char ch = S[1];

      LetterSetA << ch;

      ShowSet(LetterSetA, 1);

    }

    void __fastcall TForm1::AddToSetBBtnClick(TObject *Sender)

    {

      AnsiString S(Edit1->Text);

      char ch = S[1];

      LetterSetB << ch;

      ShowSet(LetterSetB, 2);

    }

    void __fastcall TForm1::Union1Click(TObject *Sender)

    {

      TLetterSet Union;

      Union = LetterSetA + LetterSetB;

      ShowSet(Union, 3);

    }

    void __fastcall TForm1::Intersection1Click(TObject *Sender)

    {

      TLetterSet Intersection;

      Intersection = LetterSetA * LetterSetB;

      ShowSet(Intersection, 3);

    }

    void __fastcall TForm1::Difference1Click(TObject *Sender)

    {

      TLetterSet Difference;

      Difference = LetterSetA - LetterSetB;

      ShowSet(Difference, 3);

    }
`//--------------------------------------------------------------------------` The SetBasics program uses a set of `char` instead of a set of integers:
    typedef Set <char, `A', `z'> TLetterSet;
The code for moving elements in a set has not changed significantly from the NumberSet example:
    void __fastcall TForm1::AddToSetABtnClick(TObject *Sender)

    {

      AnsiString S(Edit1->Text);

      char ch = S[1];

      LetterSetA << ch;

      ShowSet(LetterSetA, 1);

    }

    void __fastcall TForm1::AddToSetBBtnClick(TObject *Sender)

    {

      AnsiString S(Edit1->Text);

      char ch = S[1];

      LetterSetB << ch;

      ShowSet(LetterSetB, 2);
    }
> The difference here, of course, is that two sets are being used, and that you can only add elements to each set. NOTE: Just before the release of C++Builder, the team changed the way the first character of an `AnsiString` is accessed. It is now indexed at the first position in the array, rather than at position zero:
>     char ch = S[1];  // First character of string

>     char ch = S[0];  // References nothing, incorrect reference!
This change came so late in the product cycle that I may not reference it correctly in all cases where the subject is brought up in this text. However, I should have caught all references in the code that appears on the CD-ROM that accompanies this book. Once you have created two sets that interest you, you can press a button on the applications form to see the union, difference, or intersection of the sets. Here, for instance, is how to create the intersection of two sets:
    void __fastcall TForm1::Intersection1Click(TObject *Sender)

    {

      TLetterSet Intersection;

      Intersection = LetterSetA * LetterSetB;

      ShowSet(Intersection, 3);

    }
The `*` operator of the `Set` template is used to perform the operation. You use the `+` operator to find the union of two sets and the `-` operator to show the difference between two sets:
    Union = LetterSetA + LetterSetB;

    Difference = LetterSetA - LetterSetB;
The main form for the program is shown in Listing 3.6. Suppose you have two sets that look like this:
    <`A', `B', `E'>     <`B', `G'>
The union of the sets would look like this: `<`A', `B', `E', `G'>`. The intersection would look like this: `<`B'>`. The difference, if you subtracted the second from the first, would look like this: `<`A', `E'>`. You can experiment with the program further if you want to see more about creating the intersection, union, or difference of two sets. If you look in `SysDefs.h` or in the online help, you will see that there are also operators that enable you to test for equality or to see if one set is larger than another. ### A Few Additional Points about Sets You can add multiple items to a set with the following syntax:
    NumSet << 2 << 3 << 5;
Here, for instance, is a real-world case of adding or removing items from a `TNavigator` control:
    FMyNavigator->VisibleButtons =

        TButtonSet() << nbFirst << nbLast << nbNext << nbPrior;
In general, sets are very easy to use, though their syntax is not particularly inviting at first glance. Once again, it is important to remember that this `Set` class is meant for use with the VCL. The `Set` class in `SysDefs.h` is not a general purpose set class, and it is not meant as a substitute for the code you find in the Standard Template Library. As with much of the code shown in this chapter, the key point that justifies the existence of the `Set` class is its compatibility with certain features of the VCL. Two such features have been illustrated in the last few pages. The first illustrative example is the preceding `FMyNavigator` code, and the `MsgDialog` code shown back at the beginning of this discussion of sets:
    MessageDlg(S, mtInformation, TMsgDlgButtons() << mbOK, 0);
`TMsgDlgButtons` is a set class. It has the following declaration:
    enum TMsgDlgBtn { mbYes, mbNo, mbOK, mbCancel, mbAbort,

                      mbRetry, mbIgnore, mbAll, mbHelp };

    typedef Set<TMsgDlgBtn, mbYes, mbHelp>  TMsgDlgButtons;
It should now be obvious how to use this set. The elements of the set consist of all the items in the `TMsgDlgBtn` enumerated type. The set itself ranges from a low value of `mbYes` to a high value of `mbHelp`. If you wanted All and Ignore buttons on a `MessageBox`, you could write the following code to display it to the user:
    MessageDlg(S, mtInformation, TMsgDlgButtons() << mbAll << mbIgnore, 0);
The second parameter to `MessageDlg` contains a value from the following enumerated type:
    enum TMsgDlgType { mtWarning, mtError, mtInformation, mtConfirmation, mtCustom };
## Use the Source, Luke! You might notice that I frequently refer directly to the various header files that ship with BCB. Getting to know as much as possible about the source for the VCL and for BCB is a worthwhile endeavor. There are times when I use the Tool menu to make it even easier to get at source files that I use a lot. You can configure the Tools menu in BCB to run any program you like. As a result, I sometimes ask it to start Notepad (also known as Visual Notepad) or some other editor with the source from a key header file in it. To do this 1. Open the Tools menu and select Configure. 2. In the Title field, give your new menu item a name, such as `SysDefs`. 3. In the Program field, enter the name of the executable you want to run, such as Notepad, Visual SlickEdit, CodeWright, or MultiEdit. 4. Set up a working directory, which is usually the place where the include files are located: `g:\bcb\include\vcl`. 5. Pass in the name of the file you want to launch in the Parameters field. 6. Click the Close button. The way this process looks in action is shown in Figure 3.5. Figure 3.5.Using the Tools menu to create a means for automatically opening a header file whenever you need it. If possible, and especially if you are using Windows 95, you should find a real editor to use with large header files. Good ones include Visual SlickEdit from MicroEdge, MultiEdit from American Cybernetics, and CodeWright from Premia. ## Getting the Heap Status To understand what is happening in your program, you should become familiar with the `THeapStatus` class from `SYSDEFS.HPP`:
    class THeapStatus {

      public:

        Cardinal TotalAddrSpace;

        Cardinal TotalUncommitted;

        Cardinal TotalCommitted;

        Cardinal TotalAllocated;

        Cardinal TotalFree;

        Cardinal FreeSmall;

        Cardinal FreeBig;

        Cardinal Unused;

        Cardinal Overhead;

        Cardinal HeapErrorCode;

    } ;
To retrieve an instance of this type, you can call `GetHeapStatus`:
    THeapStatus HeapStatus = GetHeapStatus();
The values retrieved by a call to `GetHeapStatus` tell you about the condition of the heap for your program. They do not refer to global memory for the machine on which your program is running. This call will probably fail if made from inside a DLL. ## Variants Variants are an OLE-based type in the VCL that can be assigned to a wide range of variable types. Some people jokingly refer to variants as a typeless type, because it can be used to represent a string, an integer, an object, or several other types. The following is a simple procedure that illustrates the flexible nature of variants:
    void __fastcall TForm1::BitBtn1Click(TObject *Sender)

    {

      Variant V;

      V = 1;

      V = "Sam";
    }
This procedure compiles fine under BCB. As you can see, you are allowed to assign both a string and an integer to the same variant variable. The following procedure is also legal:
    void __fastcall TForm1::BitBtn1Click(TObject *Sender)

    {

      Variant V;

      V = 1;

      Caption = "Sam" + V;
    }
The attempt to assign `Edit1.Text` to a variant concatenated with a string would have been flagged as a type mismatch by Delphi because a variant in Object Pascal takes on some of the attributes of an integer after being assigned to that type. The `Variant` class implemented in `SYSDEFS.H`, however, allows this kind of behavior and handles it properly. Underneath the surface, variant types are represented by a 16-byte structure found in `SYSDEFS.H`. At the time of this writing, that structure looks like this:
    class TVarData {

      public:

        Word VType;

        Word Reserved1;

        Word Reserved2;

        Word Reserved3;

        union {

          Smallint VSmallint;

          Integer VInteger;

          Single VSingle;

          Double VDouble;

          CurrencyBase VCurrency;

          TDateTimeBase VDate;

          PWideChar VOleStr;

          Ole2::IDispatch* VDispatch;

          Integer VError;

          WordBool VBoolean;

          Ole2::IUnknown* VUnknown;

          Byte VByte;

          Pointer VString;

          PVarArray VArray;

          Pointer VPointer;

        };
    };
Notice that this is a union; that is, the various types represented in the `switch` statement are overlaid in memory. The structure ends up being 16 bytes in size because the `VType` field is 2 bytes; the three reserved fields total 6 bytes; and the largest of the types in the variant section is the double, which is 8 bytes in size. (2 + 6 + 8 = 16.) Once again, the `switch` statement in the declaration is not a list of separate fields, but a list of different ways to interpret the 8 bytes of data contained in the second half of the space allocated for the record. The following are the declarations for the values used with variants:
    #define varEmpty (unsigned char)(0)

    #define varNull (unsigned char)(1)

    #define varSmallint (unsigned char)(2)

    #define varInteger (unsigned char)(3)

    #define varSingle (unsigned char)(4)

    #define varDouble (unsigned char)(5)

    #define varCurrency (unsigned char)(6)

    #define varDate (unsigned char)(7)

    #define varOleStr (unsigned char)(8)

    #define varDispatch (unsigned char)(9)

    #define varError (unsigned char)(10)

    #define varBoolean (unsigned char)(11)

    #define varVariant (unsigned char)(12)

    #define varUnknown (unsigned char)(13)

    #define varByte (unsigned char)(17)

    #define varString (unsigned short)(256)

    #define varTypeMask (unsigned short)(4095)

    #define varArray (unsigned short)(8192)

    #define varByRef (unsigned short)(16384)
NOTE: When you study these declarations, it's important to understand that the VCL defines a certain set of behavior to be associated with variants, but might not guarantee that the implementation will remain the same from version to version. In other words, you can almost surely count on the fact that assigning both a string and an integer to the same variant will always be safe. However, you might not necessarily be sure that variants will always be represented by the same constants and record shown previously. To check whether these implementations have been blessed as being permanent, refer to your VCL documentation. If I were writing the documentation for the VCL, I might decide not to show you the specific record shown previously because these kinds of details might change in later versions of the product, just as the internal representation for long strings might change. However, in this book I do not claim to be defining the language in a set of official documents. Instead, I am explaining the product to you, using the techniques that seem most useful. In this particular case, I think it helps to see behind the scenes and into the particulars of this implementation of the Variant type. Whether or not this will become a documented fact or an undocumented trick is not clear at the time of this writing. It should be clear from the preceding code examples that knowing what type is represented by a variant at a particular moment can be important. To check the variant's type, you can use the `VarType` function, as shown here:
    void __fastcall TForm1::BitBtn1Click(TObject *Sender)

    {

      int AType;

      Variant V;

      AType = VarType(V);

      // Additional code

    }
In this example, the `Integer` variable `AType` will be set to one of the constants shown previously. In particular, it will probably be assigned to `varEmpty`, because in the preceding example this variable has not yet been assigned to another type. If you want to get a closer look at a variant, you can typecast it to learn more about it, as shown in the following example:
    void __fastcall TForm1::BitBtn1Click(TObject *Sender)

    {

      Variant V;

      TVarData VarData;

      int AType;

      V = 1;

      VarData = TVarData(V);

      AType = VarData.VType;

    }
In this particular case, `AType` will be set to the same value that would be returned from a call to `VarType`. To understand more about how all this works, see Listing 3.7 and 3.8, in which you can find the code for the VarDatas program. This code sets a single variant to a series of different values and then examines the variant to discover the current value of its `VType` field. #### Listing 3.7. The VarDatas program lets you examine variant types. Here is the header file for the main form of the program.
    ///////////////////////////////////////

    // Copyright (c) 1997 by Charlie Calvert

    //

    #ifndef MainH

    #define MainH

    #include <vcl\Classes.hpp>

    #include <vcl\Controls.hpp>

    #include <vcl\StdCtrls.hpp>

    #include <vcl\Forms.hpp>

    class TForm1 : public TForm

    {

    __published:

      TButton *bVariantPlay;

      TListBox *ListBox1;

      void __fastcall bVariantPlayClick(TObject *Sender);

    private:

      void ShowVariant(Variant &V);

    public:

      virtual __fastcall TForm1(TComponent* Owner);

    };

    extern TForm1 *Form1;
`#endif` #### Listing 3.8. The main source file for the VarDatas program includes a routine that returns a string stating the type of a variant.
    ///////////////////////////////////////

    // Copyright (c) 1997 by Charlie Calvert

    //

    #include <vcl\vcl.h>

    #pragma hdrstop

    #include "Main.h"

    #pragma resource "*.dfm"

    TForm1 *Form1;

    __fastcall TForm1::TForm1(TComponent* Owner)

      : TForm(Owner)

    {

    }

    AnsiString GetVariantType(Variant &V)

    {

      TVarData VarData;

      AnsiString S;

      VarData = TVarData(V);

      switch (VarData.VType)

      {

        case varEmpty: S = "varEmpty"; break;

        case varNull:  S = "varNull";  break;

        case varSmallint: S = "varSmallInt";  break;

        case varInteger: S = "varInteger";  break;

        case varSingle: S = "varSingle"; break;

        case varDouble: S= "varDouble"; break;

        case varCurrency: S = "varCurrency"; break;

        case varDate: S = "varDate"; break;

        case varOleStr: S = "varOleStr"; break;

        case varDispatch: S = "varDispatch"; break;

        case varError: S = "varError"; break;

        case varBoolean: S = "varBoolean"; break;

        case varVariant: S = "varVariant"; break;

        case varUnknown: S = "varUnknown"; break;

        case varString: S = "varString"; break;

        case varTypeMask: S = "varTypeMask"; break;

        case varByRef: S = "varByRef"; break;

        case varByte: S = "varByte"; break;

        case varArray: S = "varArray"; break;

        default:

          S = "Error";

      }

      return S;

    }

    void TForm1::ShowVariant(Variant &V)

    {

      AnsiString S, Temp;

      if ((VarIsEmpty(V) == True) || (VarIsNull(V) == True))

      {

        Temp = "Null";

        S = Format("Value: %-15s  Type: %s",

          OPENARRAY(TVarRec, (Temp, GetVariantType(V))));

      }

      else

      {

        Temp = V;

        S = Format("Value: %-15s  Type: %s",

          OPENARRAY(TVarRec , (Temp, GetVariantType(V))));

      }

      ListBox1->Items->Add(S);

    }

    void __fastcall TForm1::bVariantPlayClick(TObject *Sender)

    {

      Variant V;

      ShowVariant(V);

      V = Null;

      ShowVariant(V);

      V = 1;

      ShowVariant(V);

      V = "Sam";

      ShowVariant(V);

      V = 1.25;

      ShowVariant(V);
`}` A typical run of this program is shown in Figure 3.6. Figure 3.6.The VarDatas program uses the `TVarData` structure to examine how variants are put together. The data shown in the list box in Figure 3.6 represents the value and internal representation of a single variant that is assigned a series of different types. It's important to understand that `Variant` can't simultaneously represent all types, and can instead at any one moment take on the characteristics of only one particular type. The code that assigns different types to a variant is easy to understand, as is shown here:
    void __fastcall TForm1::bVariantPlayClick(TObject *Sender)

    {

      Variant V;

      ShowVariant(V);

      V = Null;

      ShowVariant(V);

      V = 1;

      ShowVariant(V);

      V = "Sam";

      ShowVariant(V);

      V = 1.25;

      ShowVariant(V);
    }
The code that reports on the current type of a variant is somewhat more complex, but still relatively straightforward, as shown next:
    AnsiString GetVariantType(Variant &V)

    {

      TVarData VarData;

      AnsiString S;

      VarData = TVarData(V);

      switch (VarData.VType)

      {

        case varEmpty: S = "varEmpty"; break;

        case varNull:  S = "varNull";  break;

        case varSmallint: S = "varSmallInt";  break;

        case varInteger: S = "varInteger";  break;

        case varSingle: S = "varSingle"; break;

        case varDouble: S= "varDouble"; break;

        case varCurrency: S = "varCurrency"; break;

        case varDate: S = "varDate"; break;

        case varOleStr: S = "varOleStr"; break;

        case varDispatch: S = "varDispatch"; break;

        case varError: S = "varError"; break;

        case varBoolean: S = "varBoolean"; break;

        case varVariant: S = "varVariant"; break;

        case varUnknown: S = "varUnknown"; break;

        case varString: S = "varString"; break;

        case varTypeMask: S = "varTypeMask"; break;

        case varByRef: S = "varByRef"; break;

        case varByte: S = "varByte"; break;

        case varArray: S = "varArray"; break;

        default:

          S = "Error";

      }

      return S;

    }
This code first converts a variant into a variable of type `TVarData`. In doing so, it is merely surfacing the true underlying type of the variant. However, a variable of type `TVarData` will not act the same as a variable of type `Variant`. This is because the compiler provides special services for variants that it would not provide for a simple record type such as `TVarData`. It's important to note that there are at least two ways to write the first lines of code in this function. For instance, I could have written
    AnsiString GetVariantType(Variant &V)

    {

      AnsiString S;

      switch (VarType(V))

      {

        case varEmpty: S = "varEmpty"; break;

        case varNull:  S = "varNull";  break;

        // Code omitted

      }

    }
This code works the same as the code shown in the actual program found on the CD-ROM. However you decide to implement the function, the key point is that variants can take on the appearance of being of a certain type. The chameleon-like behavior of `Variant` is sparked by the type of variable to which it is assigned. If you want, you can think of a variant as a chameleon that hides itself from view by assuming the coloration of the variable to which it is assigned. A variant is never of type `Variant`; it's always either empty, `NULL`, or the type of the variable to which it is assigned. In the same way, a chameleon has no color of its own but is always changing to adapt its color to the environment around it. Either that, or it is unborn, dead, nonexistent, or has no color at all! The following routines can all be used with variants. To learn more about these routines, look in the online help.
    extern void __fastcall VarClear(Variant &V);

    extern void __fastcall VarCopy(Variant &Dest, const Variant &Source);

    extern void __fastcall VarCopyNoInd(Variant &Dest, const Variant &Source);

    extern void __fastcall VarCast(Variant &Dest, const Variant &Source, int VarType);

    extern int __fastcall VarType(const Variant &V);

    extern Variant __fastcall VarAsType(const Variant &V, int VarType);

    extern bool __fastcall VarIsEmpty(const Variant &V);

    extern bool __fastcall VarIsNull(const Variant &V);

    extern AnsiString __fastcall VarToStr(const Variant &V);

    extern Variant __fastcall VarFromDateTime(TDateTime DateTime);

    extern TDateTime __fastcall VarToDateTime(const Variant &V);
Here are some routines to use with Variant arrays.
    extern Variant __fastcall VarArrayCreate(const int *Bounds, const int Bounds_Size,int VarType);

    extern Variant __fastcall VarArrayOf(const Variant *Values, const int Values_Size);

    extern void __fastcall VarArrayRedim(Variant &A, int HighBound);

    extern int __fastcall VarArrayDimCount(const Variant &A);

    extern int __fastcall VarArrayLowBound(const Variant &A, int Dim);

    extern int __fastcall VarArrayHighBound(const Variant &A, int Dim);

    extern void * __fastcall VarArrayLock(const Variant &A);

    extern void __fastcall VarArrayUnlock(const Variant &A);

    extern Variant __fastcall VarArrayRef(const Variant &A);

    extern bool __fastcall VarIsArray(const Variant &A);
Before closing this section, I want to make it clear that variants are not meant to be used broadly in your program whenever you need to work with a variable. I have no doubt that some people will in fact program that way, but I want to emphasize that the developers didn't really want variants to be used that way. This is mainly because they have some overhead associated with them that can slow down the compiler. Some tricks performed by variants, such as string manipulation, happen to be highly optimized. However, you should never consider a variant to be as fast or efficient as a standard C type. Variants are almost certainly best used in OLE and database applications. In particular, variants were brought into the language because they play a role in OLE automation. Furthermore, much of the structure and behavior of variants is defined by the rules of OLE. These unusual types also prove to be useful in database applications. As a rule, there is so much overhead involved in referencing any value from a database that a little additional variant manipulation code is not going to make a significant difference. ## Working with Text Files Some of the best features of C++Builder are not immediately obvious to you when you first start working with the tool, or even after you have been working with the tool for awhile. For instance, C++Builder has a built in type called a `TStringList` that all but makes obsolete the concept of a text file. This class is so easy to use, and so powerful, that there are few occasions when you would want to open a text file using `fopen`. It's important to note that manipulating text files is not really the central purpose of the `TStringList` class; however, it performs this task so well that there is little need to ever resort to using `fopen`, `fclose`, and other similar commands. Before looking at how you would use to `TStringList` to open a text file, it might be helpful to point out the places in BCB where this class is most often used, as well as a few other features of the class. The `TStringList` class is a descendant of the abstract class `TStrings`. There are no instances of the `TString` class in BCB, because this is an abstract type. However, the `TStringList`, `TListBox->Items`, `TComboBox->Items`, `TMemo->Lines`, `TRichEdit->Lines` and `TQuery->VCL` classes all descend directly from `TStrings`. This means you can assign instances of these classes to one another. You can, for instance, create an instance of the `TStringList` class and assign it to a `TListBox->Items` object:
    TStringList *MyStringList = new TStringList;

    MyStringList->Add("Some text");

    MyStringList->Add("More text");

    ListBox1->Items = MyStringList;
If you write code like this, `ListBox1` will end up showing two items in it, with the first being `"Some text"`, and the second being `"More text"`. You can write the contents of any string list to file by using the `SaveToFile` method, and you can read the list back using `LoadFromFile`. There are also `SaveToStream` and `LoadFromStream` methods:
    MyStringList->SaveToFile("C:\\Sam.txt");

    MyStringList->LoadFromFile("C:\\Sam.txt");
`TStringList`s have a sort property that can enable you to sort them instantly. You can also associate an object with each string in the `TStringList` using the `InsertObject` method. Given the presence of all this flexibility in one simple-to-use object, it does not really make sense to use any other tool for handling lists of strings. It is definitely worth taking time to explore this object and to see what it can do for you. ## New Compiler Switches I will spend little time in this book talking about how to pass switches to the compiler. That subject simply is of no interest to programmers whose primary goal is rapid application development. However, even under ideal conditions, there may be times when a programmer may have to take off their RAD hat and put on their Systems programming hat. So, if you absolutely need to start tweaking the compiler, here are some new `BCC32.EXE` switches culled from the online help: New `BCC32.EXE` switches: `-Vx` switch for truly empty (0 length) `struct`s `-He` switch (`extern` types in `.OBJ`s) `-Hs` switch (smart-cached headers) New `BCC32.EXE` pragmas: `#pragma` link "obj" (object file dependencies) `#pragma` resource "res" (resource file dependencies) `#pragma` `anon_struct` on (for support of VCL variant records) New switches for the Pascal `DCC32.EXE` compiler: `-jp` switch: creates Borland C++ compatible `.OBJ` files `-jph` switch: creates C++Builder compatible header (`.HPP`) files from Object Pascal unit files (`.DCL`) `-jphn` switch: uses the Object Pascal unit name as the enclosing C++ namespace for both `.OBJ`s and `.HPP`s that are generated `-n` switch: specify `.DCU` output directory `-nh` switch: specify `.HPP` output directory `-no` switch: specify `.OBJ` output directory ## Tips On Using the Visual Tools One of the biggest problems with BCB forms is getting them to look correct in all the possible resolutions. There is probably no surefire method for achieving these ends. However, there are some tips that I have found that help. When I build forms I almost always set the `AutoScroll` property to `False`. If you do not do this, your form will always stay the same size, which means that the edges of your form will be obscured in some resolutions. To avoid this, you would have to resize the form to fit around the edges of your controls when you changed resolutions. Whatever approach you take, you simply have to view your form in at least three or four different modes before releasing it to the public. In particular, be sure to switch back and forth between Large Fonts and Small Fonts when you change resolutions. If you are a complete perfectionist, you may decide that the only solution is to have two sets of forms, one for use with Small Fonts, and the other for use with Large Fonts. Some people have a definite knack for designing good-looking forms. If you find someone who can do this, ask them to critique your forms or even to help you design them. If you find forms that you like, study them. Use whatever tricks you can find to help you create decent-looking forms. Try to leave some whitespace on your forms if you can, and make sure controls line up vertically and horizontally whenever possible. ## Summary In this chapter you saw an overview of all the key areas in which BCB and the VCL meet. This is a complicated, yet extremely important aspect of the product. I'm sure it tried your patience at times to have to go through so much dry material. However, if you have this subject firmly under your belt, you are ready to begin a serious study of BCB. You now know a good deal about how this product is put together, and why it was constructed in this particular fashion. This is the kind of knowledge for which there is no substitute. You simply have to know these kinds of things about a product before you can take advantage of its best features. BCB is a tool for using components and objects to make applications. Any type of application you can conceive of creating can be made better in Borland C++Builder than it can with any other C/C++ compiler. What do I mean by better? I mean that it can be put together faster, with a better chance of having the right design, and with fewer bugs. In order to get that power, BCB had to tap into the VCL. In this chapter you saw how it was done. One of the most important themes of this chapter was the central role played by components, properties, and events in the BCB programming model. This product does a lot of great things, but the key features that make it all possible are the support for components, properties, and events. Much of the groundwork for that support was laid out in this chapter.
| ©Copyright, Macmillan Computer Publishing. All rights reserved.